/ 
Danga-Socket-AnyEvent-0.04
River stage zero No dependents
/ Danga::Socket::AnyEvent

NAME

Danga::Socket::AnyEvent - Danga::Socket reimplemented in terms of AnyEvent

SYNOPSIS

# This will clobber the Danga::Socket namespace
# with the new implementation.
use Danga::Socket::AnyEvent;

# Then just use Danga::Socket as normal.

DESCRIPTION

This is an alternative implementation of Danga::Socket that is implemented in terms of AnyEvent, an abstraction layer for event loops. This allows Danga::Socket applications to run in any event loop supported by AnyEvent, and allows Danga::Socket applications to make use of AnyEvent-based libraries.

Loading this module will install a workalike set of functions into the Danga::Socket package. It must therefore be loaded before anything loads the real Danga::Socket. If you try to load this module after Danga::Socket has been loaded then it will die.

DIFFERENCES FROM Danga::Socket

Although this module aims to be a faithful recreation of the features and interface of Danga::Socket, there are some known differences:

  • The LoopTimeout feature will only work if the caller runs the event loop via Danga::Socket-EventLoop>; if a caller runs the AnyEvent event loop directly, or if some other library runs it, then the timeout will not take effect.

  • The PostLoopCallback feature behaves in a slightly different way than in the stock Danga::Socket. It's currently implemented via an AnyEvent idlewatcher that runs whenever the event loop goes idle after running a Danga::Socket event. This means that it will probably run at different times than it would have in Danga::Socket's own event loops.

  • The HaveEpoll method will always return true, regardless of what backend is actually implementing the event loop. Make sure to use AnyEvent's EV backend if you would like to use Epoll/KQueue/etc rather than other, less efficient mechanisms.

METHODS

CLASS->Reset()

Reset all state

CLASS->HaveEpoll()

Returns a true value if this class will use IO::Epoll for async IO.

CLASS->WatchedSockets()

Returns the number of file descriptors for which we have watchers installed.

CLASS->EnableProfiling()

Turns profiling on, clearing current profiling data.

CLASS->DisableProfiling()

Turns off profiling, but retains data up to this point

CLASS->ProfilingData()

Returns reference to a hash of data in format:

ITEM => [ utime, stime, #calls ]

CLASS->ToClose()

Return 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.

Callers must not modify the returned hash.

CLASS->AddOtherFds( [%fdmap] )

Add fds to the OtherFds hash for processing.

CLASS->SetLoopTimeout( $timeout )

Set 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.

CLASS->DebugMsg( $format, @args )

Print the debugging message specified by the sprintf-style format and args

CLASS->AddTimer( $seconds, $coderef )

Add a timer to occur $seconds from now. $seconds may be fractional, but timers are not guaranteed to fire at the exact time you ask for.

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 exit the loop.

CLASS->SetPostLoopCallback( CODEREF )

Sets post loop callback function. Pass a subref and it will be called every time the event loop finishes.

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

The callback function will be passed two parameters: \%DescriptorMap, \%OtherFds.

OBJECT METHODS

CLASS->new( $socket )

Create 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 )

Turn 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. THIS CLOSES $self. It is the same thing as calling close, except it gives you the socket to use.

$obj->close( [$reason] )

Close 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 )

Write the specified data to the underlying handle. data 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)

$obj->push_back_read( $buf )

Push back buf (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".

$obj->read( $bytecount )

Read at most bytecount bytes from the underlying handle; returns scalar ref on read, or undef on connection closed.

(VIRTUAL) $obj->event_read()

Readable event handler. Concrete deriviatives of Danga::Socket should provide an implementation of this. The default implementation will die if called.

(VIRTUAL) $obj->event_err()

Error event handler. Concrete deriviatives of Danga::Socket should provide an implementation of this. The default implementation will die if called.

(VIRTUAL) $obj->event_hup()

'Hangup' event handler. Concrete deriviatives of Danga::Socket should provide an implementation of this. The default implementation will die if called.

$obj->event_write()

Writable event handler. Concrete deriviatives 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.

$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 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 form "ip:port"

$obj->as_string()

Returns a string describing this socket.

AUTHORS

Martin Atkins <mart@degeneration.co.uk>

Based on Danga::Socket by Brad Fitzpatrick <brad@danga.com> and others.

LICENSE

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