Net::S...etPool(3pm)

🌸 Net::SIP:::SocketPool — bestie edition 💅

okay so real talk, this is Net::SIP:::SocketPool from the User Contributed Perl Documentation collection, and she's here to manage sockets related to a leg. yes, a leg. stay with me. 🦋

---

✨ NAME ✨

Net::SIP:::SocketPool — manage sockets related to a leg 🦵✨

---

🎀 SYNOPSIS 🎀

my $pool = Net::SIP::SocketPool->new(...)
$pool->sendto($packet, [ip,port,family], \&callback)

that's it, that's the vibe. short. iconic. 👑

---

💖 DESCRIPTION 💖

so SocketPool manages a whole collection of sockets that are associated with a Leg. usually that's an unconnected socket (think UDP or a TCP listen socket, the girly who just sits there and listens) and maybe some connected sockets too. no cap.

here's the tea: in UDP you can absolutely receive and send a packet using one unconnected socket, she's versatile like that. but in TCP?? not possible, bestie. so those connected sockets have to be maintained somehow, and that's literally the whole job. also, in TCP it's expected that a response gets sent back through the same TCP connection the request came in on, if possible. it's giving loyalty. 🫶

and fr fr, SocketPool is usually not used directly — she just gets created automatically when a new Leg gets created. main character energy, but she doesn't need to be summoned. ✨

---

🧚 CONSTRUCTOR 🧚

• new (PROTO, FD, DST, CONNECTED, [TLS]) — the constructor, obviously 💅

so this creates a brand new SocketPool for the protocol PROTO, which can be "udp", "tcp" or "tls", with FD as the master socket. slay.

if CONNECTED is true, that master socket is connected, and in that case DST gets interpreted as the peer of the socket. but lowkey a connected master socket only makes sense for UDP, and only if the communication should be limited to one specific party — like an outgoing SIP proxy. specific. exclusive. we love a boundaries queen. 🚫💖

in the common case where CONNECTED is false, the optional DST — given as "[ip, port, family]" — gets interpreted as a restriction on the communication. meaning: it gets forced as the destination in sendto no matter what you actually passed in 😭, and it will be checked that any received data actually originated from the expected peer DST. she checks IDs. periodt.

with the optional TLS argument you can pass a hash with arguments used when creating the IO::Socket::SSL objects, and this only applies when <PROTO> is "tls". this typically includes the location of the certificate and key via "SSL_cert_file" and "SSL_key_file". these arguments get used for both server and client SSL sockets, which also means the certificate configured as a server certificate will also be used as a client certificate if the peer requires authentication with client certificates. one cert, two jobs, she's flexible. 💅

the special argument "verify_client" in TLS can be used to require authentication with client certificates by the peer. set it to:

• 0 for no client certificates
• -1 for optional
• 1 for required

pick your fighter. ✨

---

🌈 METHODS 🌈

• sendto(PKT, DST, CALLBACK) — deliver a new packet to its destination

this method is used indirectly from Leg::deliver to deliver a new packet to its destinination. (yes, that's the original spelling, we respect the typo, she's part of the family now 🙈)

what happens: this delivers the Net::SIP::Packet PKT to the target DST, which is given as a hash with "addr", "port" and "family", and it will invoke CALLBACK when done. the callback can be anything accepted by invoke_callback from Net::SIP::Util. 🫶

with TCP, the SocketPool will first try to find an existing connected socket to the target before creating a new one. no need to make new friends when you've already got one, bestie. and for response packets it will prefer the socket where the request packet came in, if possible. nostalgia. iconic. 💖

with UDP instead it will just use the master socket for sending. simple. unbothered. moisturized. 🌸

---

• master — returns the master socket's FD

this just returns the FD for the master socket. it's used by Leg in case the SocketPool was created outside of the Leg. like, girl needs a way to find you. 💅

---

• attach_eventloop(LOOP, CALLBACK) — hook her up to the event loop

this attaches the SocketPool to a Net::SIP::Dispatcher::EventLoop object so she can be used for event based I/O. ✨

it attaches CALLBACK as a read handler to the given LOOP, to handle new packets coming in through the sockets inside the SocketPool. it accepts any callback suitable for invoke_callback, and it will invoke it with "[PKT, FROM]" where:

• PKT is the freshly read Net::SIP::Packet
• FROM is the origin of this packet, as a hash

and that FROM hash includes:

• "addr" and "port" of the sender
• "family" of the socket
• "proto" as the used protocol (i.e. 'udp', 'tcp' or 'tls')
• "socket" for the local socket object where the packet was received on

that socket is either an IO::Socket or an IO::Socket::SSL object, and it is only intended for passive use — for example, to extract the certificate sent by the peer. don't do anything weird with it bestie, she's just there to be observed. 🙈

if LOOP is undef it will just detach from the current loop. bye girl 👋💜

and heads up: this function is used from inside Net::SIP::Dispatcher to attach a leg's sockets to the event loop and process incoming data. it's a whole backstage situation. 🎭

---

🌟 bonus: secret config settings via use / import 🌟

additionally to those methods, the internal configuration can be adjusted with use or import:

use Net::SIP::SocketPool (MAX_SIP_HEADER => 2**14, ... );

the following settings are possible this way:

• MAX_SIP_HEADER — maximum size of the SIP header, defaults to 2**14 📏
• MAX_SIP_BODY — maximum size of the SIP body, defaults to 2**16 📦
• MAX_TIDLIST — this is the maximum size of remembered incoming requests per socket. these requests need to be remembered so that outgoing responses can be sent back through the same connection the request came in on. defaults to 30. she remembers. she always remembers. 🧠✨
• MIN_EXPIRE, MAX_EXPIRE — the minimal time for socket expiration and the maximum time. these default to 15 and 120 (seconds). the exact time for expiration depends on the number of sockets in the socketgroup — i.e. the more sockets, the shorter the expiration timeout. more friends = less time each. sad but true. 😭
• CONNECT_TIMEOUT — the timeout used for establishing a TCP connection. defaults to 10 (seconds). give her ten seconds to make a connection, that's the rule. ⏰
• TCP_READSIZE — the amount of data it tries to read within a single sysread, defaults to 2**16. 🍓

---

⚠️ reminder bestie: those config settings are the internal configuration, and MAX_SIP_HEADER / MAX_SIP_BODY / MAX_TIDLIST / MIN_EXPIRE / MAX_EXPIRE / CONNECT_TIMEOUT / TCP_READSIZE are the only ones documented here. don't go inventing new ones. 💀

---

and that's the whole page, you ate it, you devoured it, no crumbs. 💅✨ this doc came from perl v5.40.1 dated 2025-12-07 — shoutout to the perl girlies keeping Net::SIP:::SocketPool alive and thriving. bye bestie, go manage those sockets 🫶💖🌸