view release on metacpan or  search on metacpan

Event/Event.pm  view on Meta::CPAN

=head1 NAME

Coro::Event - do events the coro-way, with Event

=head1 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 thread for event processing, if impossible in main:
 Coro::async { Event::loop };

=head1 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
(I<flavour>) (see L<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 threads and then call
C<Event::loop>.

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

=head1 WARNING

Please note that Event does not support multithreading. That means that
you B<MUST NOT> block in an event callback. Again: In Event callbacks,
you I<must never ever> call a Coro function that blocks the current
thread.

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

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

=head1 SEMANTICS

Whenever Event blocks (e.g. in a call to C<one_event>, C<loop> etc.),
this module cede's to all other threads with the same or higher
priority. When any threads 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. Note that for this to work you actually need to
run the event loop in some thread.

=head1 FUNCTIONS

=over 4

=cut

package Coro::Event;

use common::sense;

use Carp;

use Coro;
use Event qw(loop unloop); # we are re-exporting this for historical reasons

use XSLoader;

use base Exporter::;

our @EXPORT = qw(loop unloop sweep);

BEGIN {
   our $VERSION = 6.514;

   local $^W = 0; # avoid redefine warning for Coro::ready;
   XSLoader::load __PACKAGE__, $VERSION;
}

=item $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;

=cut

=item $w->next

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