Net-Async-AMQP/lib/Net/Async/AMQP/Channel.pod
=for comment POD_DERIVED_INDEX_GENERATED
The following documentation is automatically generated. Please do not edit
this file, but rather the original, inline with Net::Async::AMQP::Channel
at lib/Net/Async/AMQP/Channel.pm
(on the system that originally ran this).
If you do edit this file, and don't want your changes to be removed, make
sure you change the first line.
=cut
=head1 NAME
Net::Async::AMQP::Channel - represents a single channel in an MQ connection
=head1 VERSION
version 2.000
=head1 SYNOPSIS
use IO::Async::Loop;
use Net::Async::AMQP;
my $loop = IO::Async::Loop->new;
$loop->add(my $amqp = Net::Async::AMQP->new);
$amqp->connect(
host => 'localhost',
username => 'guest',
password => 'guest',
)->then(sub {
shift->open_channel->publish(
type => 'application/json'
)
});
=head1 DESCRIPTION
Each Net::Async::AMQP::Channel instance represents a virtual channel for
communicating with the MQ server.
Channels are layered over the TCP protocol and most of the common AMQP frames
operate at channel level - typically you'd connect to the server, open one
channel for one-shot requests such as binding/declaring/publishing, and a further
channel for every consumer.
Since any error typically results in a closed channel, it's not recommended to
have multiple consumers on the same channel if there's any chance the Basic.Consume
request will fail.
=head1 METHODS
=head2 confirm_mode
Switches confirmation mode on for this channel.
In confirm mode, all messages must be ACKed
explicitly after delivery.
Note that this is an irreversible operation - once
confirm mode has been enabled on a channel, closing that
channel and reopening is the only way to turn off confirm
mode again.
Returns a L<Future> which will resolve with this
channel once complete.
$ch->confirm_mode ==> $ch
=head2 nowait_from_args
If we have a C<wait> argument, then return the inverse of that.
Otherwise, return zero.
=head2 exchange_declare
Declares a new exchange.
Returns a L<Future> which will resolve with this
channel once complete.
$ch->exchange_declare(
exchange => 'some_exchange',
type => 'fanout',
autodelete => 1,
) ==> $ch
=head2 exchange_bind
Binds an exchange to another exchange. This is a RabbitMQ-specific extension.
=head2 queue_declare
Returns a L<Future> which will resolve with the new L<Net::Async::AMQP::Queue> instance,
the number of messages in the queue, and the number of consumers.
$ch->queue_declare(
queue => 'some_queue',
) ==> ($q, $message_count, $consumer_count)
=head2 publish
Publishes a message on this channel.
Returns a L<Future> which will resolve with the
channel instance once the server has confirmed publishing is complete.
$ch->publish(
exchange => 'some_exchange',
routing_key => 'some.rkey.here',
type => 'some_type',
) ==> $ch
Some named parameters currently accepted - note that this list is likely to
expand in future:
=over 4
=item * ack - we default to ACK mode, so set this to 0 to turn off explicit server ACK
on message routing/delivery
=item * immediate - if set, will cause a failure if the message could not be routed
immediately to a consumer
=item * mandatory - if set, will require that the message ends up in a queue (i.e. will
fail messages sent to an exchange that do not have an appropriate binding)
=item * content_type - defaults to application/binary
=item * content_encoding - defaults to undef (none)
=item * timestamp - the message timestamp, defaults to epoch time
=item * expiration - use this to set per-message expiry, see L<https://www.rabbitmq.com/ttl.html>
=item * priority - defaults to undef (none), use this to take advantage of RabbitMQ 3.5+ priority support
=item * reply_to - which queue to reply to (used for RPC, default undef)
=item * correlation_id - unique message ID (used for RPC, default undef)
=item * delivery_mode - whether to persist message (default 1, don't persist - set to 2 for persistent, see also "durable" flag for queues)
=back
=head2 qos
Changes QOS settings on the channel. Probably most
useful for limiting the number of messages that can
be delivered to us before we have to ACK/NAK to
proceed.
Returns a L<Future> which will resolve with the
channel instance once the operation is complete.
$ch->qos(
prefetch_count => 5,
prefetch_size => 1048576,
) ==> $ch
=head2 ack
Acknowledge a specific delivery.
Returns a L<Future> which will resolve with the
channel instance once the operation is complete.
$ch->ack(
delivery_tag => 123,
) ==> $ch
=head2 nack
Negative acknowledgement for a specific delivery.
Returns a L<Future> which will resolve with the
channel instance once the operation is complete.
$ch->nack(
delivery_tag => 123,
) ==> $ch
=head2 reject
Reject a specific delivery.
Returns a L<Future> which will resolve with the
channel instance once the operation is complete.
$ch->nack(
delivery_tag => 123,
) ==> $ch
Example output:
'method_id' => 40,
'reply_code' => 404,
'class_id' => 60,
'reply_text' => 'NOT_FOUND - no exchange \'invalidchan\' in vhost \'vhost\''
=head2 on_close
Called when the channel has been closed.
=head2 send_frame
Proxy frame sending requests to the parent
L<Net::Async::AMQP> instance.
=head2 close
Ask the server to close this channel.
Returns a L<Future> which will resolve with the
channel instance once the operation is complete.
$ch->close(
code => 404,
text => 'something went wrong',
) ==> $ch
=head2 push_pending
=head2 remove_pending
Removes a coderef from the pending event handler.
Returns C< $self >.
=head2 next_pending
Retrieves the next pending handler for the given incoming frame type (see L<Net::Async::AMQP::Utils/amqp_frame_type>),
and calls it.
Takes the following parameters:
=over 4
=item * $frame - the frame itself
=back
Returns $self.
=head1 METHODS - Accessors
=head2 amqp
The parent L<Net::Async::AMQP> instance.
=head2 bus
Event bus. Used for sharing channel-specific events.
=head2 future
The underlying L<Future> for this channel.
Will resolve to the L<Net::Async::Channel> instance once the channel is open.
=head2 id
This channel ID.
=head2 closed
Returns true if the channel has been closed, 1 if not (which could mean it is either not yet open,
or that it is open and has not yet been closed by either side).
=head2 closure_protection
Helper method for marking any outstanding requests as failed when the channel closes.
Takes a L<Future>, returns a L<Future> (probably the same one).
=head1 INHERITED METHODS
=over 4
=item L<IO::Async::Notifier>
L<add_child|IO::Async::Notifier/add_child>, L<adopt_future|IO::Async::Notifier/adopt_future>, L<can_event|IO::Async::Notifier/can_event>, L<children|IO::Async::Notifier/children>, L<configure_unknown|IO::Async::Notifier/configure_unknown>, L<debug_printf|IO::Async::Notifier/debug_printf>, L<get_loop|IO::Async::Notifier/get_loop>, L<invoke_error|IO::Async::Notifier/invoke_error>, L<invoke_event|IO::Async::Notifier/invoke_event>, L<loop|IO::Async::Notifier/loop>, L<make_event_cb|IO::Async::Notifier/make_event_cb>, L<maybe_invoke_event|IO::Async::Notifier/maybe_invoke_event>, L<maybe_make_event_cb|IO::Async::Notifier/maybe_make_event_cb>, L<new|IO::Async::Notifier/new>, L<notifier_name|IO::Async::Notifier/notifier_name>, L<parent|IO::Async::Notifier/parent>, L<remove_child|IO::Async::Notifier/remove_child>, L<remove_from_parent|IO::Async::Notifier/remove_from_parent>
=back
=head1 AUTHOR
Tom Molesworth <TEAM@cpan.org>
=head1 LICENSE
Licensed under the same terms as Perl itself, with additional licensing
terms for the MQ spec to be found in C<share/amqp0-9-1.extended.xml>
('a worldwide, perpetual, royalty-free, nontransferable, nonexclusive
license to (i) copy, display, distribute and implement the Advanced
Messaging Queue Protocol ("AMQP") Specification').