.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Event 3pm"
.TH Event 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Coro::Event \- do events the coro\-way, with Event
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& use Coro;
\& use Coro::Event;
\&
\& sub keyboard : Coro {
\&    my $w = Coro::Event\->io(fd => \e*STDIN, poll => \*(Aqr\*(Aq);
\&    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 => \e*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 };
.Ve
.SH DESCRIPTION
.IX Header "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.
.PP
This module provides a method and a function for every watcher type
(\fIflavour\fR) (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.
.PP
Your application should just create all necessary threads and then call
\&\f(CW\*(C`Event::loop\*(C'\fR.
.PP
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.
.SH WARNING
.IX Header "WARNING"
Please note that Event does not support multithreading. That means that
you \fBMUST NOT\fR block in an event callback. Again: In Event callbacks,
you \fImust never ever\fR call a Coro function that blocks the current
thread.
.PP
While this seems to work superficially, it will eventually cause memory
corruption and often results in deadlocks.
.PP
Best practise is to always use \fBCoro::unblock_sub\fR for your callbacks.
.SH SEMANTICS
.IX Header "SEMANTICS"
Whenever Event blocks (e.g. in a call to \f(CW\*(C`one_event\*(C'\fR, \f(CW\*(C`loop\*(C'\fR 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.
.PP
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.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.ie n .IP "$w = Coro::Event\->flavour (args...)" 4
.el .IP "\f(CW$w\fR = Coro::Event\->flavour (args...)" 4
.IX Item "$w = Coro::Event->flavour (args...)"
Create and return a watcher of the given type.
.Sp
Examples:
.Sp
.Vb 2
\&  my $reader = Coro::Event\->io (fd => $filehandle, poll => \*(Aqr\*(Aq);
\&  $reader\->next;
.Ve
.ie n .IP $w\->next 4
.el .IP \f(CW$w\fR\->next 4
.IX 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: \f(CW\*(C`hits\*(C'\fR and \f(CW\*(C`got\*(C'\fR, both
of which return integers: the number this watcher was hit for this event,
and the mask of poll events received.
.IP "do_flavour args..." 4
.IX Item "do_flavour args..."
Create a watcher of the given type and immediately call its next method,
returning the event.
.Sp
This is less efficient then calling the constructor once and the next
method often, but it does save typing sometimes.
.IP sweep 4
.IX Item "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).
.Sp
The reason this function exists is that you sometimes want to serve events
while doing other work. Calling \f(CW\*(C`Coro::cede\*(C'\fR does not work because
\&\f(CW\*(C`cede\*(C'\fR implies that the current coroutine is runnable and does not call
into the Event dispatcher.
.SH AUTHOR/SUPPORT/CONTACT
.IX Header "AUTHOR/SUPPORT/CONTACT"
.Vb 2
\&   Marc A. Lehmann <schmorp@schmorp.de>
\&   http://software.schmorp.de/pkg/Coro.html
.Ve