Danga::Socket(3pm)

✨ Danga::Socket ✨

okay so bestie, buckle up 💖 this is the manual page for Danga::Socket, straight out of User Contributed Perl Documentation, and it's literally the blueprint for doing async socket stuff in Perl. it's giving event loop. it's giving base class. it's giving main character energy for your whole daemon. no cap.

---

🌸 NAME 🌸

Danga::Socket — event loop and event-driven async socket base class 🦋

---

🎀 SYNOPSIS 🎀

like, here's the whole vibe in code form, copy it exactly bestie:

package My::Socket
use Danga::Socket;
use base ('Danga::Socket');
use fields ('my_attribute');

sub new {
   my My::Socket $self = shift;
   $self = fields::new($self) unless ref $self;
   $self->SUPER::new( @_ );

   $self->{my_attribute} = 1234;
   return $self;
}

sub event_err { ... }
sub event_hup { ... }
sub event_write { ... }
sub event_read { ... }
sub close { ... }

$my_sock->tcp_cork($bool);

# write returns 1 if all writes have gone through, or 0 if there
# are writes in queue
$my_sock->write($scalar);
$my_sock->write($scalarref);
$my_sock->write(sub { ... });  # run when previous data written
$my_sock->write(undef);        # kick-starts

# read max $bytecount bytes, or undef on connection closed
$scalar_ref = $my_sock->read($bytecount);

# watch for writability.  not needed with ->write().  write()
# will automatically turn on watch_write when you wrote too much
# and turn it off when done
$my_sock->watch_write($bool);

# watch for readability
$my_sock->watch_read($bool);

# if you read too much and want to push some back on
# readable queue.  (not incredibly well-tested)
$my_sock->push_back_read($buf); # scalar or scalar ref

Danga::Socket->AddOtherFds(..);
Danga::Socket->SetLoopTimeout($millisecs);
Danga::Socket->DescriptorMap();
Danga::Socket->WatchedSockets();  # count of DescriptorMap keys
Danga::Socket->SetPostLoopCallback($code);
Danga::Socket->EventLoop();

---

💅 DESCRIPTION 💅

so this is an abstract base class for objects that are backed by a socket, and it hands you the whole basic framework for event-driven asynchronous IO, and it was designed to be fast. periodt. 🔥

Danga::Socket is two things at once, iconic behavior honestly: it's a base class for your objects, and it's an event loop. 💖

you (the caller) subclass Danga::Socket. the constructor registers itself with the Danga::Socket event loop, and then it invokes callbacks on your object for readability, writability, errors, and other conditions. so it's just sitting there watching, like a very competent group chat moderator. 👑

and because Danga::Socket uses the "fields" module, your subclasses must use it too. non-negotiable bestie, do not skip this. 🌸

---

🦋 MORE INFO 🦋

for now, the move is to go look at servers that already use Danga::Socket for guidance. for example: perlbal, mogilefsd, or ddlockd. go read their code, it's the real tutorial. ✨

---

🔥 API 🔥

quick note bestie: wherever you see "CLASS" down below, normally you'd call these methods like this:

Danga::Socket->method(...);

but using a subclass works too, no stress. 🫶

okay and here's the split: the CLASS methods are all the methods for the event loop part of Danga::Socket, and the object methods are all the ones you use on your subclasses. slay.

CLASS->Reset()

reset all state. clean slate, fresh start, we love a reset. 🌈

CLASS->HaveEpoll()

returns a true value if this class is gonna use IO::Epoll for async IO. 👀

CLASS->WatchedSockets()

returns the number of file descriptors registered with the global poll object. i.e. how many sockets are we watching, bestie.

CLASS->EnableProfiling()

turns profiling on, and clears the current profiling data while it's at it.

CLASS->DisableProfiling()

turns profiling off, but keeps the data you collected up to this point. 💾

CLASS->ProfilingData()

returns a reference to a hash of data, in this exact format:

ITEM => [ utime, stime, #calls ]

CLASS->ToClose()

returns the list of sockets that are awaiting close() at the end of the current event loop.

CLASS->OtherFds( [%fdmap] )

get/set the hash of file descriptors that need processing in parallel with the registered Danga::Socket objects. 😮‍💨

CLASS->AddOtherFds( [%fdmap] )

adds fds to the OtherFds hash so they get processed too.

CLASS->SetLoopTimeout( $timeout )

sets the loop timeout for the event loop to some value in milliseconds.

a timeout of 0 (zero) means poll forever. a timeout of -1 means poll and return immediately. two extremely different moods, tbh. 💀

CLASS->DebugMsg( $format, @args )

prints the debugging message specified by the "sprintf"-style format and args. 🐛

CLASS->AddTimer( $seconds, $coderef )

adds a timer to occur $seconds from now. $seconds may be fractional, but heads up — timers are not guaranteed to fire at the exact time you asked for. so don't come for it if it's a lil late. 🙈

returns a timer object which you can call $timer->cancel on if you need to. 🎀

CLASS->DescriptorMap()

get the hash of Danga::Socket objects keyed by the file descriptor (fileno) they are wrapping. 🗺️

returns a hash in list context, or a hashref in scalar context.

CLASS->EventLoop()

start processing IO events. in most daemon programs this never exits. 😭 see "PostLoopCallback" below for how to actually get out of the loop.

CLASS->SetPostLoopCallback( CODEREF )

sets the post loop callback function. pass a subref and it gets called every time the event loop finishes.

return 1 (or any true value) from the sub to make the loop continue; return 0 or false and it will exit. 🌸

the callback function gets passed two parameters: \%DescriptorMap, \%OtherFds.

OBJECT METHODS

CLASS->new( $socket )

creates a new Danga::Socket subclass object for the given socket, which will react to events on it during the "EventLoop". 🦋

this is normally (always?) called from your subclass via:

$class->SUPER::new($socket);

$obj->tcp_cork( $boolean )

turns TCP_CORK on or off depending on the value of boolean. 💅

$obj->steal_socket()

basically returns our socket and makes it so that we don't try to close it — but we do remove it from epoll handlers. ⚠️ heads up: THIS CLOSES $self. it's the same thing as calling close, except it gives you the socket to use. so like, take it, it's yours now.

$obj->close( [$reason] )

closes the socket. the reason argument will be used in debugging messages. ✨

$obj->sock()

returns the underlying IO::Handle for the object.

$obj->set_writer_func( CODEREF )

sets a function to use instead of "syswrite()" when writing data to the socket.

$obj->write( $data )

writes the specified data to the underlying handle. data may be a scalar, a scalar ref, a code ref (to run when there... it's your callback bestie), or undef just to kick-start. 💫

returns 1 if writes all went through, or 0 if there are writes in queue. if it returns 1, the caller should stop waiting for 'writable' events.

$obj->push_back_read( $buf )

pushes back buf (a scalar or a scalarref) into the read stream. useful if you read more than you needed and want to get that data back on the next "read". 🫶

$obj->read( $bytecount )

reads at most bytecount bytes from the underlying handle; returns a scalar ref on read, or undef on connection closed. and ngl this bit is important: if you call read more than once and there's no more data available after the first call, a scalar ref to an empty string is returned. 😭

(VIRTUAL) $obj->event_read()

readable event handler. concrete derivatives of Danga::Socket should provide an implementation of this. the default implementation will die if called. 💀

(VIRTUAL) $obj->event_err()

error event handler. concrete derivatives of Danga::Socket should provide an implementation of this. the default implementation will die if called. 💀

(VIRTUAL) $obj->event_hup()

'Hangup' event handler. concrete derivatives of Danga::Socket should provide an implementation of this. the default implementation will die if called. 💀

$obj->event_write()

writable event handler. concrete derivatives of Danga::Socket may wish to provide an implementation of this. the default implementation calls "write()" with an "undef". ✨

$obj->watch_read( $boolean )

turn 'readable' event notification on or off.

$obj->watch_write( $boolean )

turn 'writable' event notification on or off.

$obj->dump_error( $message )

prints to STDERR a backtrace with information about this socket and what lead up to the dump_error call. forensic queen behavior. 🔍

$obj->debugmsg( $format, @args )

print the debugging message specified by the "sprintf"-style format and args.

$obj->peer_ip_string()

returns the string describing the peer's IP. 👋

$obj->peer_addr_string()

returns the string describing the peer for the socket which underlies this object, in the form "ip:port".

$obj->local_ip_string()

returns the string describing the local IP. 🏠

$obj->local_addr_string()

returns the string describing the local end of the socket which underlies this object, in the form "ip:port".

$obj->as_string()

returns a string describing this socket.

---

👑 AUTHORS 👑

all the legends who made this happen:

• Brad Fitzpatrick <brad@danga.com> — author
• Michael Granger <ged@danga.com> — docs, testing
• Mark Smith <junior@danga.com> — contributor, heavy user, testing
• Matt Sergeant <matt@sergeant.org> — kqueue support, docs, timers, other bits

---

💀 BUGS 💀

not documented enough (but isn't that true of every project? 😭 real).

tcp_cork only works on Linux for now. no BSD push/nopush support. sad but true bestie. 🌸

---

📜 LICENSE 📜

license is granted to use and distribute this module under the same terms as Perl itself. slay, that's it. 💅

---

and that's the whole page babes 🫶 this was Danga::Socket(3pm) from perl v5.36.0, dated 2022-10-16 — go forth, subclass responsibly, and remember: don't call the virtual handlers unless you implemented them, or it will die. mwah. 🎀✨💖