AnyEve...Channel(3pm)

💖 AnyEve...Channel 💖

okay bestie, we're doing AnyEvent::RabbitMQ::Channel from the Perl docs (3pm, user contributed, the whole vibe) and I am so ready. this is the page, let's go 🦋

---

✨ NAME ✨

AnyEvent::RabbitMQ::Channel — it's an abstraction of an AMQP channel, periodt.

---

🌸 SYNOPSIS 🌸

my $ch = $rf->open_channel();
$ch->declare_exchange(exchange => 'test_exchange');

---

🎀 DESCRIPTION 🎀

so. it's a RabbitMQ channel. that's the whole thing.

a channel is a light-weight virtual connection living inside a TCP connection to a RabbitMQ broker. like, one TCP connection, many lil channels, each doing its own thing. main character energy per channel fr fr 💅

---

🫶 ARGUMENTS FOR open_channel 🫶

these are the lil guys you can hand over when you open the channel:

• on_close — a callback that fires when the channel closes. it gets passed the incoming message that caused the close, if there was one. no message, no argument, that's just how it is 😭
• on_return — a callback that fires when a mandatory or immediate message publish fails. it gets the incoming message, and bestie, that message has accessors: method_frame, header_frame, and body_frame. very demure, very mindful.

---

👑 METHODS 👑

💫 declare_exchange (%args)

declares an exchange on the server — that's the thing you publish messages to. iconic behavior.

Arguments:

• on_success — callback for the good timeline ✨
• on_failure — callback for the other timeline 💀
• type — default 'direct'
• passive — default 0
• durable — default 0
• auto_delete — default 0
• internal — default 0
• exchange — the name of the exchange

---

💫 bind_exchange

binds an exchange to another exchange, with a routing key. matching them up, yk?

Arguments:

• source — the name of the source exchange to bind
• destination — the name of the destination exchange to bind
• routing_key — the routing key to bind with

---

💫 unbind_exchange

(no args listed here, she's just doing her thing 🧚)

---

💫 delete_exchange

(same, no args listed, bye bestie 👋)

---

💫 declare_queue

declares a queue on the server — meaning it creates it if it doesn't already exist — so you can publish messages to it.

here's the whole vibe in code:

my $done    = AnyEvent->condvar;
$channel->declare_queue(
   exchange    => $queue_exchange,
   queue       => $queueName,
   durable     => 0,
   auto_delete => 1,
   passive     => 0,
   arguments   => { 'x-expires' => 0, },
   on_success  => sub { $done->send; },
   on_failure  => sub {
       say "Unable to create queue $queueName";
       $done->send;
   },
);
$done->recv;

Arguments:

• queue — name of the queue to be declared. 🚨 but wait: if the queue name is the empty string, RabbitMQ will create a unique name for the queue for you. this is lowkey the move for temporary/private reply queues. obsessed.
• on_success — callback called when the queue was declared successfully. the argument it gets is of type Net::AMQP::Frame::Method. and if you declared it with an empty name and you're like "okay but what IS the name", you can say:

on_success => sub {
    my $method = shift;
    my $name   = $method->method_frame->queue;
};

• on_failure — callback called when the declaration of the queue has failed 😔
• auto_delete — 0 or 1, default 0
• passive — 0 or 1, default 0
• durable — 0 or 1, default 0
• exclusive — 0 or 1, default 0
• no_ack — 0 or 1, default 1
• ticket — default 0
• arguments — a hashref of additional parameters which RabbitMQ extensions may use. heads up: this list is not complete, and your RabbitMQ server configuration is what decides which arguments are valid and how they act. so don't come for me if yours is different 💅
  • x-expires — the queue will automatically be removed after being idle for this many milliseconds.
    • default of 0 disables automatic queue removal. (so yes, 0 = never delete, not "delete instantly", don't get got 🙈)

---

💫 bind_queue

binds a queue to an exchange, with a routing key.

Arguments:

• queue — the name of the queue to bind
• exchange — the name of the exchange to bind
• routing_key — the routing key to bind with

---

💫 unbind_queue

(no args listed, still slaying ✨)

---

💫 purge_queue

flushes the contents of a queue. bye bye messages 🌊

---

💫 delete_queue

deletes a queue. ⚠️ important: the queue may not have any active consumers. so like, cancel those subscriptions first bestie, don't fight the broker.

---

💫 consume

subscribe to consume messages from a queue. this is the main-character move.

Arguments:

• queue — the name of the queue to be consumed from.
• on_consume — callback called with an argument of the message which has been consumed.
  • that message is a hash reference, where the value to key "header" is an object of type Net::AMQP::Protocol::Basic::ContentHeader, body is a Net::AMQP::Frame::Body, and "deliver" a Net::AMQP::Frame::Method. yes, three whole things, she's built different.
• on_cancel — callback called if consumption is cancelled. this may be at client request, or as a side effect of queue deletion. (and heads up: notification of queue deletion is a RabbitMQ extension, iykyk.)
• consumer_tag — identifies this consumer. it'll be auto-generated if you don't provide it, but you must supply a value if you want to be able to cancel the subscription later. no tag, no cancel, fr fr.
• on_success — callback called if the subscription was successful (this fires before the first message is consumed).
• on_failure — callback called if the subscription fails for any reason.
• no_ack — passes through the "no_ack" flag. defaults to 1. if it's set to 1, the server will not expect messages to be acknowledged.

---

💫 publish

publish a message to an exchange. go little message go 🦋

Arguments:

• exchange — the name of the exchange to send the message to.
• routing_key — the routing key with which to publish the message.
• header — hash of AMQP message header info, including the confusingly similar element "headers", which may contain arbitrary string key/value pairs. yes it's confusing. yes it's real. we deal 💀
• body — the text body of the message to send.
• mandatory — boolean. if true, then if the message doesn't land in a queue (like, say, the exchange has no bindings), it will be "returned." (see "on_return" below ⬇️)
• immediate — boolean. if true, then if the message cannot be delivered directly to a consumer, it will be "returned." (see "on_return" below ⬇️)
• on_ack — callback called with the frame that acknowledges receipt (if the channel is in confirm mode), typically Net::AMQP::Protocol::Basic::Ack.
• 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.
• on_return — okay so in AMQP, a "returned" message is one that cannot be delivered in compliance with the "immediate" or "mandatory" flags.
  • 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 isn't provided, then the channel or connection objects' on_return callbacks (if any) get called instead.
  • > NOTE: if confirm mode is on, the on_ack or on_nack callback will be called whether or not on_return is called first. so don't assume an order, bestie, just be ready for both 💅

---

💫 cancel

cancel a queue subscription.

📢 important nuance: the cancellation will not take place at once, and further messages may be consumed before the subscription is actually cancelled. no further messages will be consumed after the on_success callback has been called, though. so there's a lil messy middle window. that's just how she goes.

Arguments:

• consumer_tag — identifies this consumer. it needs to be the value you supplied when the queue was initially consumed from.
• on_success — callback called if the subscription was successfully cancelled.
• on_failure — callback called if the subscription could not be cancelled for any reason.

---

💫 get

try to get a single message from a queue. just one. a lil snack. 🍓

Arguments:

• queue — Mandatory. name of the queue to try to receive a message from.
• on_success — will be called either with a message, or, if the queue is empty, a notification that there was nothing to collect from the queue. (so yeah, success can mean "nothing there", be chill about it ✨)
• on_failure — this callback will be called if an error is signalled on this channel.
• no_ack — 0 or 1, default 1

---

💫 ack

(no args listed on the page, she's a vibe 🧚)

---

💫 qos

(no args listed either, still iconic)

---

💫 confirm

puts the channel into confirm mode. in confirm mode, publishes are confirmed by the server, so the on_ack callback of publish actually works. that's the whole point, bestie. 👑

---

💫 recover

(no args listed)

---

💫 select_tx

(no args listed)

---

💫 commit_tx

(no args listed)

---

💫 rollback_tx

(no args listed)

---

🌈 AUTHOR, COPYRIGHT AND LICENSE 🌈

for author(s), copyright and license, go check out AnyEvent::RabbitMQ — that's where all of it lives, this page is just the channel chapter 💖

---

and that's a wrap on the AnyEve...Channel(3pm) page from the User Contributed Perl Documentation, generated with perl v5.32.1 and dated 2021-09-12. tysm for reading, go declare some queues responsibly, mwah 🫶💅✨