Event

 view release on metacpan or  search on metacpan

lib/Event.pod  view on Meta::CPAN

=encoding utf8

=head1 NAME

Event - Event loop processing

=head1 SYNOPSIS

 use Event qw(loop unloop);
 
 # initialize application
 Event->flavor(attribute => value, ...);
    
 my $ret = loop();
    
 # and some callback will call
 unloop('ok');

=head1 DESCRIPTION

ALERT: Marc Lehmann may have taken over the future of event loops in
Perl. Check out his libev library and EV Perl module. 25 Aug 2009

The Event module provide a central facility to watch for various types
of events and invoke a callback when these events occur.  The idea is
to delay the handling of events so that they may be dispatched in
priority order when it is safe for callbacks to execute.

Events (in the ordinary sense of the word) are detected by B<watchers>,
which reify them as B<events> (in the special Event module sense).
For clarity,
the former type of events may be called "source events", and the latter
"target events".  Source events, such as signals arriving, happen whether
or not they are being watched.  If a source event occurs which a
watcher is actively watching then the watcher generates a corresponding
target event.  Target events are only created by watchers.  If several
watchers are interested in the same source event then each will
generate their own target event.  Hence, any particular source event may
result in zero, one, two, or any number of target events: the same as
the number of watchers which were actively watching for it.

Target events are queued to be processed in priority order (priority
being determined by the creating watcher) and in FIFO order among events
of the same priority.  Queued ("pending") events can, in some cases, be
cancelled before being processed.  A queued event is processed by being
passed to the callback function (or method on a particular object or class)
which was specified to the watcher.

A watcher, once created, operates autonomously without the Event user
having to retain any reference to it.  However, keeping a reference
makes it possible to modify most of the watcher's characteristics.
A watcher can be switched between active and inactive states. When
inactive, it does not generate target events.

Some types of source event are not reified as target events immediately.
Signals received, for example, are counted initially. The
counted signals are reified at certain execution points.
Hence, signal events may be processed out of order, and if handled
carelessly, on the wrong side of a state change in event handling.
A useful way to view this is that occurrence of the source
event is not actually the arrival of the signal but is triggered by the
counting of the signal.

Reification can be forced when necessary.
The schedule on which some other events are created is
non-obvious.  This is especially the case with watchers that
watch for a condition rather than an event.  In some cases,
target events are generated on a schedule that depends on the
operation of the event loop.

=head1 PERL API

Events (the occurrence of such) are noticed and queued by 'event
watchers'.  The creation and configuration of event watchers is the
primary topic of the rest of this document.
 
The following functions control or interrogate the event loop as a
whole:

=over 4

=item $result = loop([$timeout])

Will enter a loop that calls one_event() until unloop() is called.
The argument passed to unloop() is the return value of loop().  Loops
can be nested.

lib/Event.pod  view on Meta::CPAN

=item sweep([$max_prio])

Queue all pending events and dispatch any with priority strictly less
than $max_prio (the highest priority is 0).  The default is to process
all events except idle events.  (While idle B<events> are ignored by
sweep, idle watchers are B<not> ignored.  If you want to avoid
triggering an idle watcher then set C<max> to C<undef> or C<stop()> it.)

=item one_event([$timeout])

If any events are outstanding then invoke the corresponding callback
of the highest priority event.  If there are no events available,
block forever or until $timeout.  Use of this API is not recommended
because it is not efficient and does not trap exceptions.  However,
you might wish to understand how it works:

=over 4

=item 1

Queue asyncronous events (signals, etc).  That is, previously recorded
events are reified.

=item 2

If there are any events with priority 5 or less (see StarvePrio) then
service the next one and return.

=item 3

Calculate the maximum wait time (minimum time till the next timer
expiration) and pass control to the poll/select system call.  Upon
return, queue all pending events.

=item 4

Queue asyncronous events again.

=item 5

If there are any events then service the next one and return.

=item 6

Service the next idle watcher.

=back

StarvePrio is the priority level for which events are dispatched
during step 2.  It cannot be changed without a recompile.  In the rare
case that an event is always pending at step 2 then I/O watchers will
starve.  However, this is highly unlikely since async watchers should
never queue events so rapidly.

=item all_watchers()

Returns a list of all watchers (including stopped watchers).

=item all_running()

Returns a list of all watchers with actively running callbacks.
Watchers are returned in order of most recent to least recent.

=item all_idle()

Returns a list of all the idle watchers.
If the event queue is very busy, all the idle watchers will sit on the
idle queue waiting to run.  However, be aware that if an idle watcher
has the C<max> attribute set then it will queue a normal event when
its C<max> wait time is exceeded.

=item queue_pending()

Examines asynchronous source events (timers & signals) and reifies
them as target events. C<queue_pending()> is only called implicitly by
C<sweep()> and C<one_event()>.  Otherwise, C<queue_pending()> is not
called implicitly.

NOTE: Signal watchers generate target events according to which
watchers are active at the time that C<queue_pending()> is called
rather than according to the time the signal is received.  This is
best explained by example.  See the file C<demo/queue_pending.t>.

=back

=head2 Event Watcher Constructors

All watchers are constructed in one of the following ways:

  $w = Event->flavor( [attr1 => $value,]... );
 
  $w = Event::flavor($Class, [attr1 => $value,]...);

  $w = Event::flavor->new([attr1 => $value,]...);

Where I<flavor> is substituted with the kind of watcher.  Built-in
types include idle, io, signal, timer, and var.

New watchers (hopefully) have reasonable defaults and can also be
customized by passing extra attributes to the constructor.  When
created, watcher objects are "started" and are waiting for events
(see C<$event-E<gt>start> below).

NetServer::Portal can display watchers in real-time, formatted
similarly to the popular C<top> program.  You may find this a useful
aide for debugging.

=head2 Shared Watcher Attributes

Watchers are configured with attributes (also known as properties).
For example:

   $watcher->cb(\&some_code);   # set callback

   warn $event->w->desc.": ".$event->hits." events happened; Wow!";

All watchers support the following attributes: cb, cbtime, debug,
desc, prio, max_cb_tm, reentrant, and repeat.  Watcher constructors
accept the preceding and additionally: async and nice.
Moreover, watchers also offer extra
attributes according to their specialty.

lib/Event.pod  view on Meta::CPAN

method.  If you don't want the watcher started then request
C<< parked=>1 >>.

=back

=head2 WATCHER ATTRIBUTES

=over 4

=item at => $time

The expiration time in the same units as the system clock.  For a
timer, C<at> will usually be in the future.

=item cb => \&code

=item cb => [$class_or_object, $method_name]

The function or method to call when an event is dispatched.  The
callback is invoked with C<$event> as its only argument.

Perhaps you are wondering what happens if something goes wrong and an
untrapped C<die> occurs within your callback?  C<$Event::DIED> is just
for this purpose.  See the full description of C<DIED> below.

=item cbtime => $time

When the callback was invoked most recently.

=item data => $anything

The C<data()> method associates arbitrary data with a watcher.

This method is not intended for implementers of watchers.  If you are
subclassing or implementing a watcher, consider the C<private()>
method.

=item debug => $bool

Debugging can be activated globally or per watcher.  When debugging is
enabled for a particular watcher, $Event::DebugLevel is treated as two
levels higher.  Levels of 1, 2, 3, or 4 give progressively more
diagnostics on STDERR.

=item desc => $string

An identifying name.  If this is not passed explicitly to the
constructor, it will be initialized with a string that attempts to
identify the location in the source code where the watcher was
constructed.

=item fd => $filehandle

This attribute can accept either a perl-esque filehandle or a system
call derived file descriptor number.

=item hard => $bool

Determines how repeating timers (or timeouts) are recalculated.  The
timer is restarted either before or after the callback depending on
whether it is true or false, respectively.  In long-running callbacks
this can make a significant difference.

=item interval => $seconds

How long between repeating timeouts.  The C<at> attribute is
recalculated using C<interval> upon callback return.

=item max => $seconds

The maximum number of seconds to wait before triggering the callback.
Similar to a C<timeout>.

=item max_cb_tm => $seconds

The maximum number of seconds to spend in a callback.  If a callback
uses more time then it is aborted.  Defaults to 1 sec.  This feature
is normally disabled.  See Event::Stats.

=item min => $seconds

Enforce a minimum number of seconds between triggering events.

=item poll => $bits

Determines which kinds of events are of interest.  This attribute can
be set with either strings or bit constants.  The bit constants are
available via 'use Event::Watcher qw(R W E T);'.

  string constant description
  ------ -------- ---------------
   'r'     R      read
   'w'     W      write
   'e'     E      exception
   't'     T      timeout

Thus, both of these statements enable interest in read:

  $w->poll($w->poll . 'r');
  $w->poll($w->poll | R);

A given type of watcher may support all or a subset of the available
events.

=item prio => $level

Changes the watcher's priority to the given level.  Events generated
by a watcher usually inherit the priority of the watcher.

=item private => $anything

Use the C<private()> method to associate arbitrary data with a
watcher.  This method is intended for implementers of watchers or
watcher subclasses.  Each caller's package accesses its own private
attribute.

=item reentrant => $bool

By default, callbacks are allowed to invoke C<sweep> or C<loop> which
in turn may invoke the same callback again recursively.  This can be
useful but can also be confusing.  Moreover, if you keep reentering
callbacks you will quickly run out of stack space. Disable this
feature per watcher by setting reentrant to false.  This will cause
the watcher to be suspended during recursive calls to C<sweep> or
C<loop>.

=item repeat => $bool

The repeat flag controls whether the callback should either be
one-shot or continue waiting for new events.  The default setting
depends on the type of watcher.  I<io>, I<signal>, and I<var> default
to true.

=item signal => $str

The callback is invoked after the specified signal is received.  The
$str string should be something like 'INT' or 'QUIT'.  Also see the
documentation for C<%SIG>.

A given signal can be handled by C<%SIG> or Event, but not both at the
same time.  Event handles the signal as long as there is at least one
active watcher. If all watchers for the signal are cancelled or
stopped then Event sets the signal handler to SIG_DFL.

=item suspend => $bool

Stop looking for events.  Running events are allowed to complete, but
queued events are cancelled.

Suspend is for debugging.  If you suspend all watchers in an
application then you can examine the complete state unchanged for as
long as you like without worrying about timer expirations.  If you
actually wish to stop a watcher then use the C<stop()> method.

=item timeout => $seconds

The number of seconds before a watcher times out.

=item timeout_cb => \&code

=item timeout_cb => [$class_or_object, $method_name]

This is an optional attribute for use when it is desired that timeouts
be serviced in a separate code path than normal events.  When this
attribute is unset, timeouts are serviced by C<cb>.

=item var => $ref

A reference to the variable being watched.

=back

=head2 EVENT ATTRIBUTES

=over 4

=item got => $bits

C<got> is available in the callback of watchers with C<poll>.
C<got> is in the same format as C<poll> except that it gives what
kind of event actually happened.  In contrast, C<poll> is just an
indication of interest.

lib/Event.pod  view on Meta::CPAN

This method return the event's watcher.  It is read-only.

=back

=head2 Customization and Exceptions

=over 4

=item * $Event::DebugLevel

Enables progressively more debugging output.  Meaningful levels range
from 1 (least output) to 5 (most output). Also see C<debug>.

=item * $Event::DIED

When C<loop> or C<sweep> is called, an exception context is
established for the duration of event processing. If an exception is
detected then C<$Event::DIED> is invoked.  The default hook uses
C<warn> to output the exception.  After the DIED handler completes,
event processing continues as if nothing happened.

If you'd like more detailed output you can install the verbose
handler:

  $Event::DIED = \&Event::verbose_exception_handler;

Or you can write your own.  The handler is invoked like this:

  $Event::DIED->($event, $@);

If you do not want to continue looping after an error, you can do
something like this:

  $Event::DIED = sub {
    Event::verbose_exception_handler(@_);
    Event::unloop_all();
  };

=item * Event->add_hooks(key => sub { ... }, ...);

The bulk of Event's implementation is in C for B<maximum> performance.
The C<add_hooks> method allows insertion of perl code at key points in
the optimized event processing core.  While flexible, this can hurt
performance *significantly*.  If you want customization *and*
performance, please see the C API.

Currently support hooks are detailed as follows:

  hook          purpose
  ------------- ----------------------------------------------
  prepare	returns minimum time to block (timeable)
  check		assess state after normal return from select/poll
  asynccheck	check for signals, etc
  callback	invoked before each event callback

=back

=head1 C API

Event also has a direct API for callbacks written exclusively in C.
See Event::MakeMaker.

=head1 WHAT ABOUT THREADS?

Event loops and threads are two different solutions to the same
problem: asynchronous processing.  Event loops have been around since
the beginning of computing.  They are well understood and proven to be
a good solution for many applications.

While event loops make use of basic operating system services, the
bulk of their implementation is usually outside the kernel.  While an
event loop may appear to do many things in parallel, it does not, even
on multiprocessor hardware.  Actions are always dispatched
sequentially.  This implies that long running callbacks must be
avoided because otherwise event processing is halted.

Event loops work well when actions are short and to the point.
Long-running tasks must be broken into short steps and scheduled for
execution.  Some sort of a state machine is usually required.  While a
big, complex application server is usually simpler to implement in a
multithreaded fashion, a web browser can easily get by without
threads.  Consider a JPEG file download and render.  When some new
bytes are available they are sorted to the right place on the screen.
Only a little state must be kept to keep track of how much has been
rendered and to process subsequent incoming bytes.

Threads can either substitute for an event loop or complement it.
Threads are similar to processes in that the operating system manages
task switching for you.  However, the difference is that all threads
share the same address space.  This is good and bad.  Higher
performance can be achieved but since data is shared between threads,
extreme care must be taken to access or modify global data.  The
operating system can switch threads at any moment or can execute
multiple threads simultaneously.  I hope this sounds dangerous!  It
is!  Threads can introduce maddeningly complicated and hard to debug
synchronization problems.

Threads are like rocket fuel.  They are essential when you really need
them but most applications would be better off with a simple event
loop.  Even if threads are genuinely needed, consider confining them
to the parts of an application where truly scalable performance is
really worth the difficulty of a multithreaded implementation.  For
example, most GUIs applications do not need threads and most
scientific compute intensive problems can be isolated from event
dispatching.  On the other hand, high performance transaction servers
generally do mandate a truly multithreaded approach.

Another consideration is that threads are not quite as widely
available as event loops.  While a few forward-thinking operating
systems have offered threads since the beginning, their addition to
many popular operating systems is much more recent and some still
offer no threads support.  If portability is a requirement, one must
check that threads support is available and also carefully test a
particular threads implementation to see whether it supports the
features you need.  It is likely that all platforms will have a solid
implementation soon but at this point in history it is best to double
check.

Many suggestions by Mark Mielke <Mark.Mielke.markm@nt.com>

=head1 WHAT ABOUT NON-PREEMPTIVE THREADS?

The Java language is oriented to use non-preemptive threads, yet even
Java uses an event-loop for Swing (AFAIK). That is one of the reasons
I don't use Java for network-centric applications. My belief is that
the benefit of multi-threading is the gain in performance on SMP
hardware.  In my view, non-preemptive threads (java green-threads) are
usually poor design.  I find them harder to work with, harder to
debug, and slower for a rather marginal gain in readability. I really
like working with a state machine.  I find it leads to more stable and
better code. It also has the benefit of abstracting away how
concurrency is achieved.

Contributed by artur@vogon-solutions.com, 12 Jul 1999.