NAME

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

SYNOPSIS

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

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.

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.

Because Danga::Socket uses the "fields" module, your subclasses must too.

MORE INFO

For now, see servers using Danga::Socket for guidance. For example: perlbal, mogilefsd, or ddlockd.

AUTHORS

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

BUGS

Not documented enough.

epoll is only used on Linux when the arch is one of x86, x86_64, ia64, ppc, and ppc64. Mail me if you want to use this module with epoll mode on something else. (ideally with a patch)

LICENSE

License is granted to use and distribute this module under the same terms as Perl itself.