.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Danga::Socket 3"
.TH Danga::Socket 3 2024-09-01 "perl v5.40.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Danga::Socket \- Event loop and event\-driven async socket base class
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 4
\&  package My::Socket
\&  use Danga::Socket;
\&  use base (\*(AqDanga::Socket\*(Aq);
\&  use fields (\*(Aqmy_attribute\*(Aq);
\&
\&  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();
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This is an abstract base class for objects backed by a socket which
provides the basic framework for event-driven asynchronous IO,
designed to be fast.  Danga::Socket is both a base class for objects,
and an event loop.
.PP
Callers subclass Danga::Socket.  Danga::Socket's constructor registers
itself with the Danga::Socket event loop, and invokes callbacks on the
object for readability, writability, errors, and other conditions.
.PP
Because Danga::Socket uses the "fields" module, your subclasses must
too.
.SH "MORE INFO"
.IX Header "MORE INFO"
For now, see servers using Danga::Socket for guidance.  For example:
perlbal, mogilefsd, or ddlockd.
.SH API
.IX Header "API"
Note where "\f(CW\*(C`CLASS\*(C'\fR" is used below, normally you would call these methods as:
.PP
.Vb 1
\&  Danga::Socket\->method(...);
.Ve
.PP
However using a subclass works too.
.PP
The CLASS methods are all methods for the event loop part of Danga::Socket,
whereas the object methods are all used on your subclasses.
.ie n .SS """CLASS\->Reset()"""
.el .SS \f(CWCLASS\->Reset()\fP
.IX Subsection "CLASS->Reset()"
Reset all state
.ie n .SS """CLASS\->HaveEpoll()"""
.el .SS \f(CWCLASS\->HaveEpoll()\fP
.IX Subsection "CLASS->HaveEpoll()"
Returns a true value if this class will use IO::Epoll for async IO.
.ie n .SS """CLASS\->WatchedSockets()"""
.el .SS \f(CWCLASS\->WatchedSockets()\fP
.IX Subsection "CLASS->WatchedSockets()"
Returns the number of file descriptors which are registered with the global
poll object.
.ie n .SS """CLASS\->EnableProfiling()"""
.el .SS \f(CWCLASS\->EnableProfiling()\fP
.IX Subsection "CLASS->EnableProfiling()"
Turns profiling on, clearing current profiling data.
.ie n .SS """CLASS\->DisableProfiling()"""
.el .SS \f(CWCLASS\->DisableProfiling()\fP
.IX Subsection "CLASS->DisableProfiling()"
Turns off profiling, but retains data up to this point
.ie n .SS """CLASS\->ProfilingData()"""
.el .SS \f(CWCLASS\->ProfilingData()\fP
.IX Subsection "CLASS->ProfilingData()"
Returns reference to a hash of data in format:
.PP
.Vb 1
\&  ITEM => [ utime, stime, #calls ]
.Ve
.ie n .SS """CLASS\->ToClose()"""
.el .SS \f(CWCLASS\->ToClose()\fP
.IX Subsection "CLASS->ToClose()"
Return the list of sockets that are awaiting \fBclose()\fR at the end of the
current event loop.
.ie n .SS """CLASS\->OtherFds( [%fdmap] )"""
.el .SS "\f(CWCLASS\->OtherFds( [%fdmap] )\fP"
.IX Subsection "CLASS->OtherFds( [%fdmap] )"
Get/set the hash of file descriptors that need processing in parallel with
the registered Danga::Socket objects.
.ie n .SS """CLASS\->AddOtherFds( [%fdmap] )"""
.el .SS "\f(CWCLASS\->AddOtherFds( [%fdmap] )\fP"
.IX Subsection "CLASS->AddOtherFds( [%fdmap] )"
Add fds to the OtherFds hash for processing.
.ie n .SS """CLASS\->SetLoopTimeout( $timeout )"""
.el .SS "\f(CWCLASS\->SetLoopTimeout( $timeout )\fP"
.IX Subsection "CLASS->SetLoopTimeout( $timeout )"
Set the loop timeout for the event loop to some value in milliseconds.
.PP
A timeout of 0 (zero) means poll forever. A timeout of \-1 means poll and return
immediately.
.ie n .SS """CLASS\->DebugMsg( $format, @args )"""
.el .SS "\f(CWCLASS\->DebugMsg( $format, @args )\fP"
.IX Subsection "CLASS->DebugMsg( $format, @args )"
Print the debugging message specified by the \f(CW\*(C`sprintf\*(C'\fR\-style \fIformat\fR and
\&\fIargs\fR
.ie n .SS """CLASS\->AddTimer( $seconds, $coderef )"""
.el .SS "\f(CWCLASS\->AddTimer( $seconds, $coderef )\fP"
.IX Subsection "CLASS->AddTimer( $seconds, $coderef )"
Add a timer to occur \f(CW$seconds\fR from now. \f(CW$seconds\fR may be fractional, but timers
are not guaranteed to fire at the exact time you ask for.
.PP
Returns a timer object which you can call \f(CW\*(C`$timer\->cancel\*(C'\fR on if you need to.
.ie n .SS """CLASS\->DescriptorMap()"""
.el .SS \f(CWCLASS\->DescriptorMap()\fP
.IX Subsection "CLASS->DescriptorMap()"
Get the hash of Danga::Socket objects keyed by the file descriptor (fileno) they
are wrapping.
.PP
Returns a hash in list context or a hashref in scalar context.
.ie n .SS """CLASS\->EventLoop()"""
.el .SS \f(CWCLASS\->EventLoop()\fP
.IX Subsection "CLASS->EventLoop()"
Start processing IO events. In most daemon programs this never exits. See
\&\f(CW\*(C`PostLoopCallback\*(C'\fR below for how to exit the loop.
.ie n .SS """CLASS\->SetPostLoopCallback( CODEREF )"""
.el .SS "\f(CWCLASS\->SetPostLoopCallback( CODEREF )\fP"
.IX Subsection "CLASS->SetPostLoopCallback( CODEREF )"
Sets post loop callback function.  Pass a subref and it will be
called every time the event loop finishes.
.PP
Return 1 (or any true value) from the sub to make the loop continue, 0 or false
and it will exit.
.PP
The callback function will be passed two parameters: \e%DescriptorMap, \e%OtherFds.
.SS "OBJECT METHODS"
.IX Subsection "OBJECT METHODS"
.ie n .SS """CLASS\->new( $socket )"""
.el .SS "\f(CWCLASS\->new( $socket )\fP"
.IX Subsection "CLASS->new( $socket )"
Create a new Danga::Socket subclass object for the given \fIsocket\fR which will
react to events on it during the \f(CW\*(C`EventLoop\*(C'\fR.
.PP
This is normally (always?) called from your subclass via:
.PP
.Vb 1
\&  $class\->SUPER::new($socket);
.Ve
.ie n .SS """$obj\->tcp_cork( $boolean )"""
.el .SS "\f(CW$obj\->tcp_cork( $boolean )\fP"
.IX Subsection "$obj->tcp_cork( $boolean )"
Turn TCP_CORK on or off depending on the value of \fIboolean\fR.
.ie n .SS """$obj\->steal_socket()"""
.el .SS \f(CW$obj\->steal_socket()\fP
.IX Subsection "$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.  THIS CLOSES \f(CW$self\fR.  It is the same
thing as calling close, except it gives you the socket to use.
.ie n .SS """$obj\->close( [$reason] )"""
.el .SS "\f(CW$obj\->close( [$reason] )\fP"
.IX Subsection "$obj->close( [$reason] )"
Close the socket. The \fIreason\fR argument will be used in debugging messages.
.ie n .SS """$obj\->sock()"""
.el .SS \f(CW$obj\->sock()\fP
.IX Subsection "$obj->sock()"
Returns the underlying IO::Handle for the object.
.ie n .SS """$obj\->set_writer_func( CODEREF )"""
.el .SS "\f(CW$obj\->set_writer_func( CODEREF )\fP"
.IX Subsection "$obj->set_writer_func( CODEREF )"
Sets a function to use instead of \f(CWsyswrite()\fR when writing data to the socket.
.ie n .SS """$obj\->write( $data )"""
.el .SS "\f(CW$obj\->write( $data )\fP"
.IX Subsection "$obj->write( $data )"
Write the specified data to the underlying handle.  \fIdata\fR may be scalar,
scalar ref, code ref (to run when there), 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, caller should stop waiting for 'writable' events)
.ie n .SS """$obj\->push_back_read( $buf )"""
.el .SS "\f(CW$obj\->push_back_read( $buf )\fP"
.IX Subsection "$obj->push_back_read( $buf )"
Push back \fIbuf\fR (a scalar or scalarref) into the read stream. Useful if you read
more than you need to and want to return this data on the next "read".
.ie n .SS """$obj\->read( $bytecount )"""
.el .SS "\f(CW$obj\->read( $bytecount )\fP"
.IX Subsection "$obj->read( $bytecount )"
Read at most \fIbytecount\fR bytes from the underlying handle; returns scalar ref
on read, or undef on connection closed. If you call read more than once and no
more data available after the first call, a scalar ref to an empty string is
returned.
.ie n .SS "(VIRTUAL) ""$obj\->event_read()"""
.el .SS "(VIRTUAL) \f(CW$obj\->event_read()\fP"
.IX Subsection "(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.
.ie n .SS "(VIRTUAL) ""$obj\->event_err()"""
.el .SS "(VIRTUAL) \f(CW$obj\->event_err()\fP"
.IX Subsection "(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.
.ie n .SS "(VIRTUAL) ""$obj\->event_hup()"""
.el .SS "(VIRTUAL) \f(CW$obj\->event_hup()\fP"
.IX Subsection "(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.
.ie n .SS """$obj\->event_write()"""
.el .SS \f(CW$obj\->event_write()\fP
.IX Subsection "$obj->event_write()"
Writable event handler. Concrete derivatives of Danga::Socket may wish to
provide an implementation of this. The default implementation calls
\&\f(CWwrite()\fR with an \f(CW\*(C`undef\*(C'\fR.
.ie n .SS """$obj\->watch_read( $boolean )"""
.el .SS "\f(CW$obj\->watch_read( $boolean )\fP"
.IX Subsection "$obj->watch_read( $boolean )"
Turn 'readable' event notification on or off.
.ie n .SS """$obj\->watch_write( $boolean )"""
.el .SS "\f(CW$obj\->watch_write( $boolean )\fP"
.IX Subsection "$obj->watch_write( $boolean )"
Turn 'writable' event notification on or off.
.ie n .SS """$obj\->dump_error( $message )"""
.el .SS "\f(CW$obj\->dump_error( $message )\fP"
.IX Subsection "$obj->dump_error( $message )"
Prints to STDERR a backtrace with information about this socket and what lead
up to the dump_error call.
.ie n .SS """$obj\->debugmsg( $format, @args )"""
.el .SS "\f(CW$obj\->debugmsg( $format, @args )\fP"
.IX Subsection "$obj->debugmsg( $format, @args )"
Print the debugging message specified by the \f(CW\*(C`sprintf\*(C'\fR\-style \fIformat\fR and
\&\fIargs\fR.
.ie n .SS """$obj\->peer_ip_string()"""
.el .SS \f(CW$obj\->peer_ip_string()\fP
.IX Subsection "$obj->peer_ip_string()"
Returns the string describing the peer's IP
.ie n .SS """$obj\->peer_addr_string()"""
.el .SS \f(CW$obj\->peer_addr_string()\fP
.IX Subsection "$obj->peer_addr_string()"
Returns the string describing the peer for the socket which underlies this
object in form "ip:port"
.ie n .SS """$obj\->local_ip_string()"""
.el .SS \f(CW$obj\->local_ip_string()\fP
.IX Subsection "$obj->local_ip_string()"
Returns the string describing the local IP
.ie n .SS """$obj\->local_addr_string()"""
.el .SS \f(CW$obj\->local_addr_string()\fP
.IX Subsection "$obj->local_addr_string()"
Returns the string describing the local end of the socket which underlies this
object in form "ip:port"
.ie n .SS """$obj\->as_string()"""
.el .SS \f(CW$obj\->as_string()\fP
.IX Subsection "$obj->as_string()"
Returns a string describing this socket.
.SH AUTHORS
.IX Header "AUTHORS"
Brad Fitzpatrick <brad@danga.com> \- author
.PP
Michael Granger <ged@danga.com> \- docs, testing
.PP
Mark Smith <junior@danga.com> \- contributor, heavy user, testing
.PP
Matt Sergeant <matt@sergeant.org> \- kqueue support, docs, timers, other bits
.SH BUGS
.IX Header "BUGS"
Not documented enough (but isn't that true of every project?).
.PP
tcp_cork only works on Linux for now.  No BSD push/nopush support.
.SH LICENSE
.IX Header "LICENSE"
License is granted to use and distribute this module under the same
terms as Perl itself.