NAME

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

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 };

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 threads and then call "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 multithreading. That means that you MUST NOT block in an event
       callback. Again: In Event callbacks, you 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 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
       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.

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

AUTHOR/SUPPORT/CONTACT

          Marc A. Lehmann <schmorp@schmorp.de>
          http://software.schmorp.de/pkg/Coro.html

perl v5.40.1                                       2025-03-21                                         Event(3pm)