.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "AnyEvent::RabbitMQ::Channel 3pm"
.TH AnyEvent::RabbitMQ::Channel 3pm "2021-09-12" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
AnyEvent::RabbitMQ::Channel \- Abstraction of an AMQP channel.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    my $ch = $rf\->open_channel();
\&    $ch\->declare_exchange(exchange => \*(Aqtest_exchange\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A RabbitMQ channel.
.PP
A channel is a light-weight virtual connection within a \s-1TCP\s0 connection to a
RabbitMQ broker.
.ie n .SH "ARGUMENTS FOR ""open_channel"""
.el .SH "ARGUMENTS FOR \f(CWopen_channel\fP"
.IX Header "ARGUMENTS FOR open_channel"
.IP "on_close" 4
.IX Item "on_close"
Callback invoked when the channel closes.  Callback will be passed the
incoming message that caused the close, if any.
.IP "on_return" 4
.IX Item "on_return"
Callback invoked when a mandatory or immediate message publish fails.
Callback will be passed the incoming message, with accessors
\&\f(CW\*(C`method_frame\*(C'\fR, \f(CW\*(C`header_frame\*(C'\fR, and \f(CW\*(C`body_frame\*(C'\fR.
.SH "METHODS"
.IX Header "METHODS"
.SS "declare_exchange (%args)"
.IX Subsection "declare_exchange (%args)"
Declare an exchange (to publish messages to) on the server.
.PP
Arguments:
.IP "on_success" 4
.IX Item "on_success"
.PD 0
.IP "on_failure" 4
.IX Item "on_failure"
.IP "type" 4
.IX Item "type"
.PD
Default 'direct'
.IP "passive" 4
.IX Item "passive"
Default 0
.IP "durable" 4
.IX Item "durable"
Default 0
.IP "auto_delete" 4
.IX Item "auto_delete"
Default 0
.IP "internal" 4
.IX Item "internal"
Default 0
.IP "exchange" 4
.IX Item "exchange"
The name of the exchange
.SS "bind_exchange"
.IX Subsection "bind_exchange"
Binds an exchange to another exchange, with a routing key.
.PP
Arguments:
.IP "source" 4
.IX Item "source"
The name of the source exchange to bind
.IP "destination" 4
.IX Item "destination"
The name of the destination exchange to bind
.IP "routing_key" 4
.IX Item "routing_key"
The routing key to bind with
.SS "unbind_exchange"
.IX Subsection "unbind_exchange"
.SS "delete_exchange"
.IX Subsection "delete_exchange"
.SS "declare_queue"
.IX Subsection "declare_queue"
Declare a queue (create it if it doesn't exist yet) for publishing messages
to on the server.
.PP
.Vb 10
\&  my $done    = AnyEvent\->condvar;
\&  $channel\->declare_queue(
\&     exchange    => $queue_exchange,
\&     queue       => $queueName,
\&     durable     => 0,
\&     auto_delete => 1,
\&     passive     => 0,
\&     arguments   => { \*(Aqx\-expires\*(Aq => 0, },
\&     on_success  => sub { $done\->send; },
\&     on_failure  => sub {
\&         say "Unable to create queue $queueName";
\&         $done\->send;
\&     },
\&  );
\&  $done\->recv;
.Ve
.PP
Arguments:
.IP "queue" 4
.IX Item "queue"
Name of the queue to be declared. If the queue name is the empty string,
RabbitMQ will create a unique name for the queue. This is useful for
temporary/private reply queues.
.IP "on_success" 4
.IX Item "on_success"
Callback that is called when the queue was declared successfully. The argument
to the callback is of type Net::AMQP::Frame::Method. To get the name of the
Queue (if you declared it with an empty name), you can say
.Sp
.Vb 4
\&    on_success => sub {
\&        my $method = shift;
\&        my $name   = $method\->method_frame\->queue;
\&    };
.Ve
.IP "on_failure" 4
.IX Item "on_failure"
Callback that is called when the declaration of the queue has failed.
.IP "auto_delete" 4
.IX Item "auto_delete"
0 or 1, default 0
.IP "passive" 4
.IX Item "passive"
0 or 1, default 0
.IP "durable" 4
.IX Item "durable"
0 or 1, default 0
.IP "exclusive" 4
.IX Item "exclusive"
0 or 1, default 0
.IP "no_ack" 4
.IX Item "no_ack"
0 or 1, default 1
.IP "ticket" 4
.IX Item "ticket"
default 0
.IP "arguments" 4
.IX Item "arguments"
\&\f(CW\*(C`arguments\*(C'\fR is a hashref of additional parameters which RabbitMQ extensions
may use. This list is not complete and your RabbitMQ server configuration will
determine which arguments are valid and how they act.
.RS 4
.IP "x\-expires" 4
.IX Item "x-expires"
The queue will automatically be removed after being idle for this many milliseconds.
.Sp
Default of 0 disables automatic queue removal.
.RE
.RS 4
.RE
.SS "bind_queue"
.IX Subsection "bind_queue"
Binds a queue to an exchange, with a routing key.
.PP
Arguments:
.IP "queue" 4
.IX Item "queue"
The name of the queue to bind
.IP "exchange" 4
.IX Item "exchange"
The name of the exchange to bind
.IP "routing_key" 4
.IX Item "routing_key"
The routing key to bind with
.SS "unbind_queue"
.IX Subsection "unbind_queue"
.SS "purge_queue"
.IX Subsection "purge_queue"
Flushes the contents of a queue.
.SS "delete_queue"
.IX Subsection "delete_queue"
Deletes a queue. The queue may not have any active consumers.
.SS "consume"
.IX Subsection "consume"
Subscribe to consume messages from a queue.
.PP
Arguments:
.IP "queue" 4
.IX Item "queue"
The name of the queue to be consumed from.
.IP "on_consume" 4
.IX Item "on_consume"
Callback called with an argument of the message which has been consumed.
.Sp
The message is a hash reference, where the value to key \f(CW\*(C`header\*(C'\fR is an object
of type Net::AMQP::Protocol::Basic::ContentHeader, body is a
Net::AMQP::Frame::Body, and \f(CW\*(C`deliver\*(C'\fR a Net::AMQP::Frame::Method.
.IP "on_cancel" 4
.IX Item "on_cancel"
Callback called if consumption is cancelled.  This may be at client request
or as a side effect of queue deletion.  (Notification of queue deletion is a
RabbitMQ extension.)
.IP "consumer_tag" 4
.IX Item "consumer_tag"
Identifies this consumer, will be auto-generated if you do not provide it, but you must
supply a value if you want to be able to later cancel the subscription.
.IP "on_success" 4
.IX Item "on_success"
Callback called if the subscription was successful (before the first message is consumed).
.IP "on_failure" 4
.IX Item "on_failure"
Callback called if the subscription fails for any reason.
.IP "no_ack" 4
.IX Item "no_ack"
Pass through the \f(CW\*(C`no_ack\*(C'\fR flag. Defaults to \f(CW1\fR. If set to \f(CW1\fR, the server
will not expect messages to be acknowledged.
.SS "publish"
.IX Subsection "publish"
Publish a message to an exchange.
.PP
Arguments:
.IP "exchange" 4
.IX Item "exchange"
The name of the exchange to send the message to.
.IP "routing_key" 4
.IX Item "routing_key"
The routing key with which to publish the message.
.IP "header" 4
.IX Item "header"
Hash of \s-1AMQP\s0 message header info, including the confusingly similar element \*(L"headers\*(R",
which may contain arbitrary string key/value pairs.
.IP "body" 4
.IX Item "body"
The text body of the message to send.
.IP "mandatory" 4
.IX Item "mandatory"
Boolean; if true, then if the message doesn't land in a queue (e.g. the exchange has no
bindings), it will be \*(L"returned.\*(R"  (see \*(L"on_return\*(R")
.IP "immediate" 4
.IX Item "immediate"
Boolean; if true, then if the message cannot be delivered directly to a consumer, it
will be \*(L"returned.\*(R"  (see \*(L"on_return\*(R")
.IP "on_ack" 4
.IX Item "on_ack"
Callback called with the frame that acknowledges receipt (if channel is in confirm mode),
typically Net::AMQP::Protocol::Basic::Ack.
.IP "on_nack" 4
.IX Item "on_nack"
Callback called with the frame that declines receipt (if the channel is in confirm mode),
typically Net::AMQP::Protocol::Basic::Nack or Net::AMQP::Protocol::Channel::Close.
.IP "on_return" 4
.IX Item "on_return"
In \s-1AMQP,\s0 a \*(L"returned\*(R" message is one that cannot be delivered in compliance with the
\&\f(CW\*(C`immediate\*(C'\fR or \f(CW\*(C`mandatory\*(C'\fR flags.
.Sp
If in confirm mode, this callback will be called with the frame that reports message
return, typically Net::AMQP::Protocol::Basic::Return.  If confirm mode is off or
this callback is not provided, then the channel or connection objects' on_return
callbacks (if any), will be called instead.
.Sp
\&\s-1NOTE:\s0 If confirm mode is on, the on_ack or on_nack callback will be called whether or
not on_return is called first.
.SS "cancel"
.IX Subsection "cancel"
Cancel a queue subscription.
.PP
Note that the cancellation \fBwill not\fR take place at once, and further messages may be
consumed before the subscription is cancelled. No further messages will be
consumed after the on_success callback has been called.
.PP
Arguments:
.IP "consumer_tag" 4
.IX Item "consumer_tag"
Identifies this consumer, needs to be the value supplied when the queue is initially
consumed from.
.IP "on_success" 4
.IX Item "on_success"
Callback called if the subscription was successfully cancelled.
.IP "on_failure" 4
.IX Item "on_failure"
Callback called if the subscription could not be cancelled for any reason.
.SS "get"
.IX Subsection "get"
Try to get a single message from a queue.
.PP
Arguments:
.IP "queue" 4
.IX Item "queue"
Mandatory. Name of the queue to try to receive a message from.
.IP "on_success" 4
.IX Item "on_success"
Will be called either with either a message, or, if the queue is empty,
a notification that there was nothing to collect from the queue.
.IP "on_failure" 4
.IX Item "on_failure"
This callback will be called if an error is signalled on this channel.
.IP "no_ack" 4
.IX Item "no_ack"
0 or 1, default 1
.SS "ack"
.IX Subsection "ack"
.SS "qos"
.IX Subsection "qos"
.SS "confirm"
.IX Subsection "confirm"
Put channel into confirm mode.  In confirm mode, publishes are confirmed by
the server, so the on_ack callback of publish works.
.SS "recover"
.IX Subsection "recover"
.SS "select_tx"
.IX Subsection "select_tx"
.SS "commit_tx"
.IX Subsection "commit_tx"
.SS "rollback_tx"
.IX Subsection "rollback_tx"
.SH "AUTHOR, COPYRIGHT AND LICENSE"
.IX Header "AUTHOR, COPYRIGHT AND LICENSE"
See AnyEvent::RabbitMQ for author(s), copyright and license.