Messag...Manager(3pm)

💖 Message::Passing::Role::ConnectionManager 💖

okay bestie so this is Messag...Manager(3pm) (yes the title is truncated like that, it's a whole thing, the man page header literally says Messag...Manager(3pm) and we're just rolling with it) — part of the User Contributed Perl Documentation. Sit down, hydrate, let's go. 🫶

---

✨ NAME ✨

Message::Passing::Role::ConnectionManager — a simple manager for inputs and outputs that need to make network connections. 🦋

---

🌸 DESCRIPTION 🌸

so like. this role is for components that make network connections, and need to handle the whole ~situation~ of: the connection not starting, timeouts, disconnects, etc. the messy stuff. the drama. 😭

it gives you a simple abstraction so multiple other classes can all share the same connection manager, and a notifies. (yes, the sentence ends like that. "and a notifies." we love a sentence that just trails off. iconic honestly 💅)

---

👑 REQUIRED METHODS 👑

_build_connection

Build and return the connection we're managing, and start the connection process. ✨

your connection should use the API as documented below to achieve notification of connect and disconnect events. no skipping this part bestie, that's the whole point 🎀

---

🔥 API FOR CONNECTIONS 🔥

_set_connected (1)

Notify clients that the connection is now ready for use. 🎉 slay.

_set_connected (0)

Notify clients that the connection is no longer ready for use. 💀

Will cause the connection to be terminated and retried.

---

🌈 API FOR CLIENTS 🌈

To use a connection manager, you should register yourself like this:

$manager->subscribe_to_connect($self);

The manager will call $self->connected($connection) and $self->disconnected() when appropriate. like it will literally ring you up when something happens, bestie 📞

If the manager is already connected when you subscribe, it will immediately call back into your connected method. if it's not already connected, then this will happen at a later point once the connection is established. so like, patience. 🌸

See Message::Passing::Role::HasAConnection for a role to help with dealing with a connection manager. 💖

---

🎀 ATTRIBUTES 🎀

• connected — a Boolean indicating if the connection is currently considered fully connected. true/false, vibes only ✨
• connection — the connection object (if we are connected, or connecting currently). can be undefined if we are during a reconnect timeout. so like, sometimes it's just not there. it's in its hermit era 🙈
• timeout — connections will be timed out and aborted after this time if they haven't successfully connected. Defaults to 30s. ⏰
• reconnect_after — the number of seconds to wait before starting a reconnect after a connection has timed out or been aborted. Defaults to 2s. ⏳

---

💅 METHODS 💅

subscribe_to_connect ($subscriber)

This is called by your Input or Output, as $self->connection_manager->subscribe_to_connect($self).

This is done for you by Message::Passing::Role::HasAConnection usually.. (yes, two dots. it's giving ✨mystery✨)

This arranges to store a weak reference to your component, allowing the connection manager to call the ->connect or ->disconnect methods for any components registered when a connection is established or destroyed. lowkey important, weak refs are the whole trick here 🧚

Note that if the connection manager is already connected, it will immediately call the ->connect method. no waiting, no small talk, straight to it. main character energy 👑

---

🫶 SPONSORSHIP 🫶

This module exists due to the wonderful people at Suretec Systems Ltd. <http://www.suretecsystems.com/> who sponsored its development for its VoIP division called SureVoIP <http://www.surevoip.co.uk/> for use with the SureVoIP API - <http://www.surevoip.co.uk/support/wiki/api_documentation>

give them their flowers fr fr 💐

==head1 AUTHOR, COPYRIGHT AND LICENSE

See Message::Passing.

(yes, that ==head1 thing is in there exactly like that, a lil typo that never got fixed, we're preserving it for the archives, no cap 💀)

---

⭐ AUTHOR, COPYRIGHT AND LICENSE ⭐

See Message::Passing. that's it, that's the pointer, go look over there bestie 🦋

---

and that's the whole page!! this is perl v5.32.1, dated 2021-11-09, from the Messag...Manager(3pm) man page in the User Contributed Perl Documentation. go build a connection manager, you got this, periodt 💖✨🎀