NAME

LWP::EventLoop - Watch file descriptors and timers

SYNOPSIS

 use LWP::EventLoop;
 $mainloop = LWP::EventLoop->new;
 $mainloop->readable(\*STDIN, sub {sysread(STDIN, $buf, 100)});
 $mainloop->after(10, sub { print "10 sec later"} );
 $mainloop->run;

DESCRIPTION

The LWP::EventLoop class define objects that can watch file descriptors and timers and will invoke callback methods when events on these happens. Usually you will only have a single instance of this class in any application. The LWP::MainLoop module creates a single instance and provide an interface to it. The LWP::EventLoop is really just a wrapping of the select() function.

The following methods are provided:

$e = LWP::EventLoop->new

The constructor takes now arguments.

$e->readable($io, [$callback])

Register the specified IO handle as being monitored for readable status. When the handle becomes readable the specified callback will be invoked. The handle can be unregistered by giving an undef argument as the $callback.

Callbacks can either by an CODE reference (which is called with the handle as argument) or they can be a plain scalar strings which are taken to be method names that are called on the given handle object. The callback can also be an array reference. The first element of the array must be a CODE reference or a method name. The rest is taken to be additional arguments passed during callback invocation.

The default callback is to invoke the $io->readable method.

$e->writable($io, [$callback])

Like $e->readable, but watch the handle for writable status. The default callback to invoke is the $io->writable method.

$e->timeout($io, $secs, [$callback])

Register a callback to be invoked if nothing happens on the given IO handle for some number of seconds. Callbacks take the same form as for $e->readable. The default callback is to invoke the $io->inactive method. Pass 0 as the $secs argument to disable timeout for this handle.

$e->activity($io, [$time]);

Return time of last activity on the specified handle. This is only valid if you have asked for a timeout() callback on the specified handle previously.

The optional $time argument can be used to set this to some specified value. If no $time argument is provided then the current time is recorded. If the $time value is undef then the activity timestamp is not changed.

$e->after($secs, $timer_callback)

Set up a callback to be invoked after the given number of seconds. The callback must be a CODE reference. This method returns an identifier that can be used to cancel this timer using the $e->forget method.

$e->at($time, $timer_callback)

Set up a callback to be invoked at the given time. The $e->after is really the same as $e->at(time + $secs, $timer_callback).

$e->forget($io_timer,...)

Unregister all callbacks for the given IO handles and timers. One or more arguments can be given. Each argument can either be an IO handle reference or an identifier as returned by $e->after or $e->at.

$e->forget_all

Unregister all callbacks. The state of the LWP::EventLoop will be as after construction.

$e->empty

Return TRUE if no timer callbacks or IO handles to watch are registered.

$e->one_event( [$timeout] )

Wait for a single event to happen (but no longer than $timeout seconds) and call the corresponding callback routine. Can also return without calling any callback routine.

$e->run( [$timeout] )

Call $e->one_event until either all timer callbacks and IO handles are gone or until the specified number of seconds has elapsed.

$e->dump

Will print the state of the LWP::EventLoop object to the currently selected file handle. Mainly useful for debugging. Setting the $LWP::EventLoop::DEBUG variable to an TRUE value can also be useful while debugging.

SEE ALSO

LWP::MainLoop

COPYRIGHT

Copyright 1997-1998, Gisle Aas

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.