POE::C...PubSub(3pm)

📦

version 0.05 · 2 versions

0.05 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
0.05 · ubuntu jammy

, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

POE::Component::PubSub — a generic publish/subscribe POE::Component that lets POE::Sessions publish events, and lets other POE::Sessions subscribe to them. it's giving group chat but for events bestie 💬✨

🎀 VERSION 🎀

Version 0.04

✨ SYNOPSIS ✨

# Instantiate the publish/subscriber with the alias "pub"
POE::Component::PubSub->new('pub');

# Publish an event called "FOO". +PUBLISH_OUTPUT is actually optional.
$_[KERNEL]->post('pub', 'publish', 'FOO', +PUBLISH_OUTPUT);

# Elsewhere, subscribe to that event, giving it an event to call
# when the published event is fired.
$_[KERNEL]->post('pub', 'subscribe', 'FOO', 'FireThisEvent');

# Fire off the published event
$_[KERNEL]->post('pub', 'FOO');

# Publish an 'input' event
$_[KERNEL]->post('pub', 'publish', 'BAR', +PUBLISH_INPUT, 'MyInputEvent');

# Tear down the whole thing
$_[KERNEL]->post('pub', 'destroy');

🦋 EVENTS 🦋

okay so all the public events do a lil sanity check before they let anything through — they make sure the session posting the event actually owns the event it's publishing, and that the return event you pass in during subscription is owned by the sender. if either of those vibes are off, an error gets carp'd, the event just returns, and execution keeps going. no crash, just a lil side-eye 🙈

'publish' — this is the one you use to publish events. it takes one argument: the event you wanna publish. the published event can't already be published (no duplicates bestie). the event name can be literally anything and the publisher doesn't even have to implement it — think of it as the name of a mailing list 📬

you can also publish an 'input' or inverse event. this lets arbitrary sessions post to your event. in that case you have to supply the optional published event type and the event to be called when the published event fires.

there are two types: PUBLISH_INPUT and PUBLISH_OUTPUT. PUBLISH_OUPUT is implied when no argument is supplied.

'subscribe' — the event you use when subscribing to published events. it takes two arguments: 1) the published event, and 2) the event name of the subscriber to be called when the published event fires. the event does not need to be published before you subscribe — that's on purpose, it resolves chicken-and-egg problems in an async environment 🐣 but the sender must own and implement the return event.
'rescind' — use this to stop publication of an event. takes one argument: the published event. the event has to be published, and published by the sender of the rescind event. if the published event still has subscribers, a warning gets carp'd but execution keeps going. messy but we move 💅
'cancel' — cancel subscriptions to events with this one. takes one argment (yes, "argment", iconic typo, we keep it 🫶): the published event. the event must be published and the sender must be subscribed to it.
'_default' — after an event is published, the publisher may arbitrarily fire that event at this component, and all the subscribers get notified by having their respective return events called with whatever arguments the publisher passed. for the event to propagate it must be published, owned by the publisher, and have subscribers. if any subscriber no longer has a valid return event, their subscription gets cancelled and a warning gets carp'd.
'listing' — call this event to receive an array reference containing tuples of the event name and the type of the events currently published inside the component. it takes one argument: the return event to fire with the listing. the sender must own the return event 📋
'destroy' — this event just destroys all its current state and removes any and all aliases this session may have picked up. this should free up the session for garbage collection 🗑️✨

👑 CLASS METHODS 👑

POE::Component::PubSub->new($alias) — the constructor for the publish/subscribe component. it instantiates its own session, using the $alias you pass in to set its kernel alias. if you don't provide an alias, the default alias is 'PUBLISH_SUBSCRIBE'.

🔥 DEBUGGING 🔥

$POE::Component::PubSub::TRACE_AND_DEBUG — to enable debugging inside the component at the POE::Session level, plus various warnings, set this variable to logical true BEFORE calling new(). order matters bestie, don't skip it ⚠️

💀 NOTES 💀

right now this component is extremely simple, but thorough when it comes to checking all the various requirements for publishing and subscribing. currently there's no mechanism to place meta-subscriptions to the events of the component itself. that feature is planned for the next release 👀

also, to do some of the checking on whether subscribers own the return events, some ideas were lifted from POE::API::Peek, and just like that module, if there are changes to the POE core, they may break this module. so like... heads up 🫠

🌈 AUTHOR 🌈

Nicholas R. Perez, "<nperez at cpan.org>"

🐛 BUGS 🐛

please report any bugs or feature requests to bug-poe-component-pubsub at rt.cpan.org, or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-PubSub>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.