NAME

Coro::Event - do events the coro-way

SYNOPSIS

use Coro;
use Coro::Event;

sub keyboard : Coro {
   my $w = Coro::Event->io(fd => \*STDIN, poll => 'r');
   while() {
      print "cmd> ";
      my $ev = $w->next; my $cmd = <STDIN>;
      unloop unless $cmd ne "";
      print "data> ";
      my $ev = $w->next; my $data = <STDIN>;
   }
}

loop;

# wait for input on stdin for one second

Coro::Event::do_io (fd => \*STDIN, timeout => 1) & Event::Watcher::R
   or die "no input received";

# use a separate coroutine for event processing, if impossible in main:
Coro::async { Event::loop };

DESCRIPTION

This module enables you to create programs using the powerful Event model (and module), while retaining the linear style known from simple or threaded programs.

This module provides a method and a function for every watcher type (flavour) (see Event). The only difference between these and the watcher constructors from Event is that you do not specify a callback function - it will be managed by this module.

Your application should just create all necessary coroutines and then call Coro::Event::loop.

Please note that even programs or modules (such as Coro::Handle) that use "traditional" event-based/continuation style will run more efficient with this module then when using only Event.

WARNING

Please note that Event does not support coroutines or threads. That means that you MUST NOT block in an event callback. Again: In Event callbacks, you must never ever call a Coroutine function that blocks the current coroutine.

While this seems to work superficially, it will eventually cause memory corruption and often results in deadlocks.

Best practise is to always use Coro::unblock_sub for your callbacks.

SEMANTICS

Whenever Event blocks (e.g. in a call to one_event, loop etc.), this module cede's to all other coroutines with the same or higher priority. When any coroutines of lower priority are ready, it will not block but run one of them and then check for events.

The effect is that coroutines with the same or higher priority than the blocking coroutine will keep Event from checking for events, while coroutines with lower priority are being run, but Event checks for new events after every cede.

FUNCTIONS

$w = Coro::Event->flavour (args...)

Create and return a watcher of the given type.

Examples:

my $reader = Coro::Event->io(fd => $filehandle, poll => 'r');
$reader->next;

$w->next

Wait for and return the next event of the event queue of the watcher. The returned event objects support two methods only: hits and got, both of which return integers: the number this watcher was hit for this event, and the mask of poll events received.

do_flavour args...

Create a watcher of the given type and immediately call it's next method, returning the event.

This is less efficient then calling the constructor once and the next method often, but it does save typing sometimes.

sweep

Similar to Event::one_event and Event::sweep: The idle task is called once (this has the effect of jumping back into the Event loop once to serve new events).

The reason this function exists is that you sometimes want to serve events while doing other work. Calling Coro::cede does not work because cede implies that the current coroutine is runnable and does not call into the Event dispatcher.

$result = loop([$timeout])

This is the version of loop you should use instead of Event::loop when using this module - it will ensure correct scheduling in the presence of events.

unloop([$result])

Same as Event::unloop (provided here for your convinience only).

AUTHOR

Marc Lehmann <schmorp@schmorp.de>
http://home.schmorp.de/