AnyEvent::MQTT(3)

📦 version 1.212810, in alpine 3.24

💅 AnyEvent::MQTT(3) — the manual, but make it make sense

okay so welcome to AnyEvent::MQTT(3), bestie 💖 this is the perl doc page for the AnyEvent::MQTT module, aka an AnyEvent module for an MQTT client. yes you read that right. let's get into it 🫶

✨ VERSION ✨

version 1.212810 🎀 (yes it's a version number, no it's not a phone number, don't call it)

🌸 SYNOPSIS 🌸

here's the whole vibe in code, literally just copy-paste energy:

  use AnyEvent::MQTT;
  my $mqtt = AnyEvent::MQTT->new;
  my $cv = $mqtt->subscribe(topic => '/topic',
                            callback => sub {
                                 my ($topic, $message) = @_;
                                 print $topic, ' ', $message, "\n"
                               });
  my $qos = $cv->recv; # subscribed, negotiated QoS == $qos

  # publish a simple message
  $cv = $mqtt->publish(message => 'simple message',
                          topic => '/topic');
  $cv->recv; # sent

  # publish line-by-line from file handle
  $cv =  $mqtt->publish(handle => \*STDIN,
                        topic => '/topic');
  $cv->recv; # sent

  # publish from AnyEvent::Handle
  $cv = $mqtt->publish(handle => AnyEvent::Handle->new(my %handle_args),
                       topic => '/topic');
  $cv->recv; # sent

see that $cv->recv? that's you waiting for it to actually go through. the comments are the receipts btw 💅

🦋 DESCRIPTION 🦋

AnyEvent module for MQTT client. that's the whole thing. that's the sentence. 🎯

IMPORTANT: this is an early release and the API is still subject to change. so like… don't build your whole personality on it yet 🙈 the vibes are immaculate but the API is not final. no cap.

👑 METHODS 👑

🍓 new(%params)

Constructs a new AnyEvent::MQTT object. and like, the supported parameters are (pay attention bestie, there's a lot):

  • host — the server host. defaults to 127.0.0.1.
  • port — the server port. defaults to 1883.
  • timeout — the timeout for responses from the server.
  • keep_alive_timer — the keep alive timer.
  • user_name — the user name for the MQTT broker.
  • password — the password for the MQTT broker.
  • tls — set flag to enable TLS encryption. default is no encryption (yes, plaintext, be aware 😭).
  • will_topic — set topic for will message. default is undef, which means no will message will be configured.
  • will_qos — set QoS for will message. default is 'at-most-once'.
  • will_retain — set retain flag for will message. default is 0.
  • will_message — set message for will message. default is the empty message.
  • clean_session — set clean session flag for connect message. default is 1.
  • client_id — sets the client id for the client, overriding the default which is "NetMQTTpmNNNNN" where NNNNN is the current process id.
  • message_log_callback — defines a callback to call on every message.
  • on_error — defines a callback to call when some error occurs.

two parameters are passed to the callback:

$on_error->($fatal, $message)

where $fatal is a boolean flag and $message is the error message. if the error is fatal, $fatal is true. 🚨

  • handle_args — a reference to a list to pass as arguments to the AnyEvent::Handle constructor (defaults to an empty list reference).

🧚 cleanup()

this method attempts to destroy any resources in the event of a disconnection or fatal error. it's giving "closing the tab when the group chat gets too messy" energy 💀 but like, for resources.

🌈 publish( %parameters )

this method is used to publish to a given topic. it returns an AnyEvent condvar which is notified when the publish is complete (written to the kernel or ack'd depending on the QoS level). so you know it's done-done ✨

the parameter hash must include at least a topic value and one of:

  • message — with a string value which is published to the topic,
  • handle — the value of which must either be an AnyEvent::Handle or will be passed to an AnyEvent::Handle constructor as the fh argument. the push_read() method is called on the AnyEvent::Handle with a callback that will publish each chunk read to the topic.

the parameter hash may also [have] keys for:

  • qos — to set the QoS level for published messages (default MQTT_QOS_AT_MOST_ONCE),
  • handle_args — a reference to a list to pass as arguments to the AnyEvent::Handle constructor in the final case above (defaults to an empty list reference), or
  • push_read_args — a reference to a list to pass as the arguments to the AnyEvent::Handle#push_read method (defaults to ['line'] to read, and subsequently publish, a line at a time.

⭐ next_message_id()

Returns a 16-bit number to use as the next message id in a message requiring an acknowledgement. little number, big responsibility 🫡

💜 subscribe( %parameters )

this method subscribes to the given topic. the parameter hash may contain values for the following keys:

  • topic — for the topic to subscribe to (this is required),
  • callback — for the callback to call with messages (this is required),
  • qos — QoS level to use (default is MQTT_QOS_AT_MOST_ONCE),
  • cv — AnyEvent condvar to use to signal the subscription is complete. the received value will be the negotiated QoS level.

this method returns the value of the cv parameter if it was supplied, or an AnyEvent condvar created for this purpose. 🎀

🌸 unsubscribe( %parameters )

this method unsubscribes to the given topic. the parameter hash may contain values for the following keys:

  • topic — for the topic to unsubscribe from (this is required),
  • callback — for the callback to call with messages (this is optional and currently not supported — all callbacks are unsubscribed),
  • cv — AnyEvent condvar to use to signal the unsubscription is complete.

this method returns the value of the cv parameter if it was supplied, or an AnyEvent condvar created for this purpose. 🫶

heads up: the callback key? optional but also not supported yet. it's giving "coming soon" placeholder energy 🙈 all callbacks get unsubscribed regardless.

🔥 "connect( [ $msg ] )"

this method starts the connection to the server. it will be called lazily when required [by] publish or subscribe, so generally it should not be necessary to call it directly. main character energy btw — shows up exactly when needed and not a second earlier 💅

🎯 anyevent_read_type()

this method is used to register an AnyEvent::Handle read type method to read MQTT messages. lowkey iconic plumbing ngl.

💀 DISCLAIMER 💀

this is not official IBM code. the author works for IBM but wrote this in their spare time (with permission) for fun. fr fr. big "hobby project but make it corporate-adjacent" vibes 😭

💖 AUTHOR 💖

Mark Hindess <soft-cpan@temporalanomaly.com>

this software is copyright (c) 2014 by Mark Hindess.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. slay. 🫶

and that's the page bestie ✨ this doc was served up by perl v5.42.2, dated 2026-04-15 — same energy as a timestamped selfie, but for a manual page 💅📸 ok bye love u, go write some MQTT 🌸

📦 where this page comes from