Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Mojo::RabbitMQ::ClientUseraContributed Perl Mojo::RabbitMQ::Client::Channel(3)

NAME
       Mojo::RabbitMQ::Client::Channel - handles all channel related methods

SYNOPSIS
	 use Mojo::RabbitMQ::Client::Channel;

	 my $channel = Mojo::RabbitMQ::Client::Channel->new();

	 $channel->catch(sub { warn "Some channel error	occurred: " . $_[1] });

	 $channel->on(
	   open	=> sub {
	     my	($channel) = @_;
	     ...
	   }
	 );
	 $channel->on(close => sub { warn "Channel closed" });

	 $client->open_channel($channel);

DESCRIPTION
       Mojo::RabbitMQ::Client::Channel allows one to call all channel related
       methods.

EVENTS
       Mojo::RabbitMQ::Client::Channel inherits	all events from
       Mojo::EventEmitter and can emit the following new ones.

   open
	 $channel->on(open => sub {
	   my ($channel) = @_;
	   ...
	 });

       Emitted when channel receives Open-Ok.

   close
	 $channel->on(close=> sub {
	   my ($channel, $frame) = @_;
	   ...
	 });

       Emitted when channel gets closed, $frame	contains close reason.

ATTRIBUTES
       Mojo::RabbitMQ::Client::Channel has following attributes.

   id
	 my $id	= $channel->id;
	 $channel->id(20810);

       If not set, Mojo::RabbitMQ::Client sets it to next free number when
       channel is opened.

   is_open
	 $channel->is_open ? "Channel is open" : "Channel is closed";

   is_active
	 $channel->is_active ? "Channel	is active" : "Channel is not active";

       This can	be modified on reception of Channel-Flow.

   client
	 my $client = $channel->client;
	 $channel->client($client);

METHODS
       Mojo::RabbitMQ::Client::Channel inherits	all methods from
       Mojo::EventEmitter and implements the following new ones.

   close
	 $channel->close;

       Cancels all consumers and closes	channel	afterwards.

   declare_exchange
	 my $exchange =	$channel->declare_exchange(
	   exchange => 'mojo',
	   type	=> 'fanout',
	   durable => 1,
	   ...
	 )->deliver;

       Verify exchange exists, create if needed.

       This method creates an exchange if it does not already exist, and if
       the exchange exists, verifies that it is	of the correct and expected
       class.

       Following arguments are accepted:

       exchange
	 Unique	exchange name

       type
	 Each exchange belongs to one of a set of exchange types implemented
	 by the	server.	The exchange types define the functionality of the
	 exchange - i.e. how messages are routed through it. It	is not valid
	 or meaningful to attempt to change the	type of	an existing exchange.

       passive
	 If set, the server will reply with Declare-Ok if the exchange already
	 exists	with the same name, and	raise an error if not. The client can
	 use this to check whether an exchange exists without modifying	the
	 server	state. When set, all other method fields except	name and no-
	 wait are ignored. A declare with both passive and no-wait has no
	 effect. Arguments are compared	for semantic equivalence.

       durable
	 If set	when creating a	new exchange, the exchange will	be marked as
	 durable. Durable exchanges remain active when a server	restarts. Non-
	 durable exchanges (transient exchanges) are purged if/when a server
	 restarts.

       auto_delete
	 If set, the exchange is deleted when all queues have finished using
	 it.

       internal
	 If set, the exchange may not be used directly by publishers, but only
	 when bound to other exchanges.	 Internal exchanges are	used to
	 construct wiring that is not visible to applications.

   declare_exchange_p
       Same as declare_exchange	but auto-delivers method and returns a
       Mojo::Promise object.

	 $channel->declare_exchange_p(
	   exchange => 'mojo',
	   type	=> 'fanout',
	   durable => 1,
	   ...
	 )->then(sub {
	   say "Exchange declared...";
	 })->catch(sub {
	   my $err = shift;
	   warn	"Exchange declaration error: $err";
	 })->wait;

   delete_exchange
	 $channel->delete_exchange(exchange => 'mojo')->deliver;

       Delete an exchange.

       This method deletes an exchange.	When an	exchange is deleted all	queue
       bindings	on the exchange	are cancelled.

       Following arguments are accepted:

       exchange
	 Exchange name.

       if_unused
	 If set, the server will only delete the exchange if it	has no queue
	 bindings. If the exchange has queue bindings the server does not
	 delete	it but raises a	channel	exception instead.

   delete_exchange_p
       Same as delete_exchange but auto-delivers method	and returns a
       Mojo::Promise object.

	 $channel->delete_exchange_p(
	   exchange => 'mojo'
	 )->then(sub {
	   say "Exchange deleted...";
	 })->catch(sub {
	   my $err = shift;
	   warn	"Exchange removal error: $err";
	 })->wait;

   declare_queue
	 my $queue = $channel->declare_queue(queue => 'mq', durable => 1)->deliver

       Declare queue, create if	needed.

       This method creates or checks a queue. When creating a new queue	the
       client can specify various properties that control the durability of
       the queue and its contents, and the level of sharing for	the queue.

       Following arguments are accepted:

       queue
	 The queue name	MAY be empty, in which case the	server MUST create a
	 new queue with	a unique generated name	and return this	to the client
	 in the	Declare-Ok method.

       passive
	 If set, the server will reply with Declare-Ok if the queue already
	 exists	with the same name, and	raise an error if not. The client can
	 use this to check whether a queue exists without modifying the	server
	 state.	When set, all other method fields except name and no-wait are
	 ignored. A declare with both passive and no-wait has no effect.
	 Arguments are compared	for semantic equivalence.

       durable
	 If set	when creating a	new queue, the queue will be marked as
	 durable. Durable queues remain	active when a server restarts. Non-
	 durable queues	(transient queues) are purged if/when a	server
	 restarts. Note	that durable queues do not necessarily hold persistent
	 messages, although it does not	make sense to send persistent messages
	 to a transient	queue.

       exclusive
	 Exclusive queues may only be accessed by the current connection, and
	 are deleted when that connection closes. Passive declaration of an
	 exclusive queue by other connections are not allowed.

       auto_delete
	 If set, the queue is deleted when all consumers have finished using
	 it. The last consumer can be cancelled	either explicitly or because
	 its channel is	closed.	If there was no	consumer ever on the queue, it
	 won't be deleted. Applications	can explicitly delete auto-delete
	 queues	using the Delete method	as normal.

   declare_queue_p
       Same as declare_queue but auto-delivers method and returns a
       Mojo::Promise object.

	 $channel->declare_queue_p(
	   queue => 'mq',
	   durable => 1
	 )->then(sub {
	   say "Queue declared...";
	 })->catch(sub {
	   my $err = shift;
	   warn	"Queue declaration error: $err";
	 })->wait;

   bind_queue
	 $channel->bind_queue(
	   exchange => 'mojo',
	   queue => 'mq',
	   routing_key => ''
	 )->deliver;

       Bind queue to an	exchange.

       This method binds a queue to an exchange. Until a queue is bound	it
       will not	receive	any messages. In a classic messaging model, store-and-
       forward queues are bound	to a direct exchange and subscription queues
       are bound to a topic exchange.

       Following arguments are accepted:

       queue
	 Specifies the name of the queue to bind.

       exchange
	 Name of the exchange to bind to.

       routing_key
	 Specifies the routing key for the binding. The	routing	key is used
	 for routing messages depending	on the exchange	configuration. Not all
	 exchanges use a routing key - refer to	the specific exchange
	 documentation.	If the queue name is empty, the	server uses the	last
	 queue declared	on the channel.	 If the	routing	key is also empty, the
	 server	uses this queue	name for the routing key as well. If the queue
	 name is provided but the routing key is empty,	the server does	the
	 binding with that empty routing key. The meaning of empty routing
	 keys depends on the exchange implementation.

   bind_queue_p
       Same as bind_queue but auto-delivers method and returns a Mojo::Promise
       object.

	 $channel->bind_queue_p(
	   exchange => 'mojo',
	   queue => 'mq',
	   routing_key => ''
	 )->then(sub {
	   say "Queue bound...";
	 })->catch(sub {
	   my $err = shift;
	   warn	"Queue binding error: $err";
	 })->wait;

   unbind_queue
	 $channel->unbind_queue(
	   exchange => 'mojo',
	   queue => 'mq',
	   routing_key => ''
	 )->deliver;

       Unbind a	queue from an exchange.

       This method unbinds a queue from	an exchange.

       Following arguments are accepted:

       queue
	 Specifies the name of the queue to unbind.

       exchange
	 The name of the exchange to unbind from.

       routing_key
	 Specifies the routing key of the binding to unbind.

   unbind_queue_p
       Same as unbind_queue but	auto-delivers method and returns a
       Mojo::Promise object.

	 $channel->unbind_queue_p(
	   exchange => 'mojo',
	   queue => 'mq',
	   routing_key => ''
	 )->then(sub {
	   say "Queue unbound...";
	 })->catch(sub {
	   my $err = shift;
	   warn	"Queue unbinding error:	$err";
	 })->wait;

   purge_queue
	 $channel->purge_queue(queue =>	'mq')->deliver;

       Purge a queue.

       This method removes all messages	from a queue which are not awaiting
       acknowledgment.

       Following arguments are accepted:

       queue
	 Specifies the name of the queue to purge.

   purge_queue_p
       Same as purge_queue but auto-delivers method and	returns	a
       Mojo::Promise object.

	 $channel->purge_queue_p(
	   queue => 'mq',
	 )->then(sub {
	   say "Queue purged...";
	 })->catch(sub {
	   my $err = shift;
	   warn	"Queue purging error: $err";
	 })->wait;

   delete_queue
	 $channel->delete_queue(queue => 'mq', if_empty	=> 1)->deliver;

       Delete a	queue.

       This method deletes a queue. When a queue is deleted any	pending
       messages	are sent to a dead-letter queue	if this	is defined in the
       server configuration, and all consumers on the queue are	cancelled.

       Following arguments are accepted:

       queue
	 Specifies the name of the queue to delete.

       if_unused
	 If set, the server will only delete the queue if it has no consumers.
	 If the	queue has consumers the	server does does not delete it but
	 raises	a channel exception instead.

       if_empty
	 If set, the server will only delete the queue if it has no messages.

   delete_queue_p
       Same as delete_queue but	auto-delivers method and returns a
       Mojo::Promise object.

	 $channel->delete_queue_p(
	   queue => 'mq',
	   if_empty => 1
	 )->then(sub {
	   say "Queue removed...";
	 })->catch(sub {
	   my $err = shift;
	   warn	"Queue removal error: $err";
	 })->wait;

   publish
	 my $message = $channel->publish(
	   exchange    => 'mojo',
	   routing_key => 'mq',
	   body	       => 'simple text body',
	 );
	 $message->deliver();

       Publish a message.

       This method publishes a message to a specific exchange. The message
       will be routed to queues	as defined by the exchange configuration and
       distributed to any active consumers when	the transaction, if any, is
       committed.

       Following arguments are accepted:

       exchange
	 Specifies the name of the exchange to publish to. The exchange	name
	 can be	empty, meaning the default exchange. If	the exchange name is
	 specified, and	that exchange does not exist, the server will raise a
	 channel exception.

       routing_key
	 Specifies the routing key for the message. The	routing	key is used
	 for routing messages depending	on the exchange	configuration.

       mandatory
	 This flag tells the server how	to react if the	message	cannot be
	 routed	to a queue.  If	this flag is set, the server will return an
	 unroutable message with a Return method.  If this flag	is zero, the
	 server	silently drops the message.

	 All rejections	are emitted as "reject"	event.

	   $message->on(reject => sub {
	     my	$message = shift;
	     my	$frame = shift;
	     my	$method_frame =	$frame->method_frame;

	     my	$reply_code = $method_frame->reply_code;
	     my	$reply_text = $method_frame->reply_text;
	   });

       immediate
	 This flag tells the server how	to react if the	message	cannot be
	 routed	to a queue consumer immediately. If this flag is set, the
	 server	will return an undeliverable message with a Return method. If
	 this flag is zero, the	server will queue the message, but with	no
	 guarantee that	it will	ever be	consumed.

	 As said above,	all rejections are emitted as "reject" event.

	   $message->on(reject => sub {	... });

   consume
	 my $consumer =	$channel->consume(queue	=> 'mq');
	 $consumer->on(message => sub {	... });
	 $consumer->deliver;

       This method asks	the server to start a "consumer", which	is a transient
       request for messages from a specific queue. Consumers last as long as
       the channel they	were declared on, or until the client cancels them.

       Following arguments are accepted:

       queue
	 Specifies the name of the queue to consume from.

       consumer_tag
	 Specifies the identifier for the consumer. The	consumer tag is	local
	 to a channel, so two clients can use the same consumer	tags. If this
	 field is empty	the server will	generate a unique tag.

	   $consumer->on(success => sub	{
	     my	$consumer = shift;
	     my	$frame = shift;

	     my	$consumer_tag =	$frame->method_frame->consumer_tag;
	   });

       no_local	(not implemented in RabbitMQ!)
	 If the	no-local field is set the server will not send messages	to the
	 connection that published them.

	 See RabbitMQ Compatibility and	Conformance
	 <https://www.rabbitmq.com/specification.html>

       no_ack
	 If this field is set the server does not expect acknowledgements for
	 messages. That	is, when a message is delivered	to the client the
	 server	assumes	the delivery will succeed and immediately dequeues it.
	 This functionality may	increase performance but at the	cost of
	 reliability. Messages can get lost if a client	dies before they are
	 delivered to the application.

       exclusive
	 Request exclusive consumer access, meaning only this consumer can
	 access	the queue.

   cancel
	 $channel->cancel(consumer_tag => 'amq.ctag....')->deliver;

       End a queue consumer.

       This method cancels a consumer. This does not affect already delivered
       messages, but it	does mean the server will not send any more messages
       for that	consumer. The client may receive an arbitrary number of
       messages	in between sending the cancel method and receiving the cancel-
       ok reply.

       Following arguments are accepted:

       consumer_tag
	 Holds the consumer tag	specified by the client	or provided by the
	 server.

   get
	 my $get = $channel->get(queue => 'mq')
	 $get->deliver;

       Direct access to	a queue.

       This method provides a direct access to the messages in a queue using a
       synchronous dialogue that is designed for specific types	of application
       where synchronous functionality is more important than performance.

       This is simple event emitter to which you have to subscribe. It can
       emit:

       message
	 Provide client	with a message.

	 This method delivers a	message	to the client following	a get method.
	 A message delivered by	'get-ok' must be acknowledged unless the no-
	 ack option was	set in the get method.

	 You can access	all get-ok reply parameters as below:

	   $get->on(message => sub {
	     my	$get = shift;
	     my	$get_ok	= shift;
	     my	$message = shift;

	     say "Still	got: " . $get_ok->method_frame->message_count;
	   });

       empty
	 Indicate no messages available.

	 This method tells the client that the queue has no messages available
	 for the client.

       Following arguments are accepted:

       queue
	 Specifies the name of the queue to get	a message from.

       no_ack
	 If this field is set the server does not expect acknowledgements for
	 messages. That	is, when a message is delivered	to the client the
	 server	assumes	the delivery will succeed and immediately dequeues it.
	 This functionality may	increase performance but at the	cost of
	 reliability. Messages can get lost if a client	dies before they are
	 delivered to the application.

   ack
	 $channel->ack(delivery_tag => 1);

       Acknowledge one or more messages.

       When sent by the	client,	this method acknowledges one or	more messages
       delivered via the Deliver or Get-Ok methods. When sent by server, this
       method acknowledges one or more messages	published with the Publish
       method on a channel in confirm mode. The	acknowledgement	can be for a
       single message or a set of messages up to and including a specific
       message.

       Following arguments are accepted:

       delivery_tag
	 Server	assigned delivery tag that was received	with a message.

       multiple
	 If set	to 1, the delivery tag is treated as "up to and	including", so
	 that multiple messages	can be acknowledged with a single method. If
	 set to	zero, the delivery tag refers to a single message. If the
	 multiple field	is 1, and the delivery tag is zero, this indicates
	 acknowledgement of all	outstanding messages.

   qos
	 $channel->qos(prefetch_count => 1)->deliver;

       Sets specified Quality of Service to channel, or	entire connection.
       Accepts following arguments:

       prefetch_size
	 Prefetch window size in octets.

       prefetch_count
	 Prefetch window in complete messages.

       global
	 If set	all settings will be applied connection	wide.

   recover
	 $channel->recover(requeue => 0)->deliver;

       Redeliver unacknowledged	messages.

       This method asks	the server to redeliver	all unacknowledged messages on
       a specified channel. Zero or more messages may be redelivered.

       requeue
	 If this field is zero,	the message will be redelivered	to the
	 original recipient. If	this bit is 1, the server will attempt to
	 requeue the message, potentially then delivering it to	an alternative
	 subscriber.

   reject
	 $channel->reject(delivery_tag => 1, requeue =>	0)->deliver;

       Reject an incoming message.

       This method allows a client to reject a message.	It can be used to
       interrupt and cancel large incoming messages, or	return untreatable
       messages	to their original queue.

       Following arguments are accepted:

       delivery_tag
	 Server	assigned delivery tag that was received	with a message.

       requeue
	 If requeue is true, the server	will attempt to	requeue	the message.
	 If requeue is false or	the requeue attempt fails the messages are
	 discarded or dead-lettered.

   select_tx
       Work with transactions.

       The Tx class allows publish and ack operations to be batched into
       atomic units of work.  The intention is that all	publish	and ack
       requests	issued within a	transaction will complete successfully or none
       of them will. Servers SHOULD implement atomic transactions at least
       where all publish or ack	requests affect	a single queue.	Transactions
       that cover multiple queues may be non-atomic, given that	queues can be
       created and destroyed asynchronously, and such events do	not form part
       of any transaction.  Further, the behaviour of transactions with
       respect to the immediate	and mandatory flags on Basic.Publish methods
       is not defined.

	 $channel->select_tx()->deliver;

       Select standard transaction mode.

       This method sets	the channel to use standard transactions. The client
       must use	this method at least once on a channel before using the	Commit
       or Rollback methods.

   commit_tx
	 $channel->commit_tx()->deliver;

       Commit the current transaction.

       This method commits all message publications and	acknowledgments
       performed in the	current	transaction. A new transaction starts
       immediately after a commit.

   rollback_tx
	 $channel->rollback_tx()->deliver;

       Abandon the current transaction.

       This method abandons all	message	publications and acknowledgments
       performed in the	current	transaction. A new transaction starts
       immediately after a rollback. Note that unacked messages	will not be
       automatically redelivered by rollback; if that is required an explicit
       recover call should be issued.

SEE ALSO
       Mojo::RabbitMQ::Client, Mojo::RabbitMQ::Client::Method,
       Net::AMQP::Protocol::v0_8

COPYRIGHT AND LICENSE
       Copyright (C) 2015-2017,	Sebastian Podjasek and others

       Based on	AnyEvent::RabbitMQ - Copyright (C) 2010	Masahito Ikuta,
       maintained by "bobtfish@bobtfish.net"

       This program is free software, you can redistribute it and/or modify it
       under the terms of the Artistic License version 2.0.

perl v5.32.0			  2019-08-20Mojo::RabbitMQ::Client::Channel(3)

NAME | SYNOPSIS | DESCRIPTION | EVENTS | ATTRIBUTES | METHODS | SEE ALSO | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Mojo::RabbitMQ::Client::Channel&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help