=head1 NAME

Event - Event loop processing

=head1 SYNOPSIS

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

=head1 DESCRIPTION

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.

=head1 PERL API

Events (the occurance 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.

=item unloop($result)

Make the inner-most loop() return with $result.

=item unloop_all($result)

Cause all pending loop()s to return immediately.  This is B<not>
implemented with C<die>.  It is works as if C<unloop($result)> were
called for all nested loops.

=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 suspend 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.

=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()

Return all watchers on the idle queue.

=back

=head2 Event Watcher Constructors

All watchers are constructed in one of the following ways:

  $w = Event->type( [attr1 => $value,]... );
 
or
 
  use Event::type;
  $w = Event::type( [attr1 => $value,]...);

Where I<type> is substituted with the kind of watcher.  Built-in types
include idle, inactivity, 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).

=head2 Shared Watcher Attributes

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

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

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

All watchers support at least the following attributes: cb, clump,
hits, prio, desc, repeat, debug, and reentrant.  Most watchers also
offer additional attributes according to their specialty.  Moreover,
some attributes only meaningful when passed to a constructor.

=head2 Shared Watcher Methods

The following non-attribute methods are available:

=over 4

=item $watcher->start

Activate the watcher.  Most constructors return already active
watchers.

=item $watcher->again

This is the same as the C<start> except if a watcher has special
repeat behavior.  For example, repeating timers recalcuate their alarm
time using the C<interval> parameter.

=item $watcher->now

Cause the watcher to generate an event.  The callback may or may not
run immediately depending upon the event's priority.  If you must
unconditionally invoke the callback, consider something like

  $w->cb->($w);

=item $watcher->stop

Don't look for events any more.  Running events are allowed to
complete but pending events are cancelled.  Note that a stopped
watcher can be reactivated by calling the C<start> or C<again>
methods.

=item $watcher->cancel

Stop and destroy C<$watcher>.  Running events are allowed to complete
but pending events are cancelled.  If an attempt is made to use
C<$watcher> after calling C<cancel> then an exception will be thrown.

=back

=head2 Watcher Types

=over 4

=item idle

Extra attributes: min => $seconds, max => $seconds

The callback is invoked only when no events are pending.  In the
callback is not triggered by idling, an event will be generated at
least every C<max> seconds and not more often than C<min> seconds.

=item inactivity

Extra attributes: level => $level, timeout => $seconds

Not yet documented.

=item var

Extra attributes: var => \$var, poll => 'rw'

=item timer

Extra attributes: at => $time, interval => $sec, hard => $bool

The C<$time> and C<$sec> are in seconds.  Fractional seconds may be
used if L<Time::HiRes> is available.  The constructor also accepts an
C<after> attribute for easier initialization.  It might be useful to
know the time at the start of today.  You can find it with:

  use Time::Local;
  my $TodaySeconds = int timelocal(0,0,0,(localtime)[3,4,5]);

If C<interval> is set then the watcher will automatically repeat.  Be
aware that due to lags in the event loop, the C<interval> timeout may
already be in the past.  If the C<hard> flag is set, the event will be
queued for execution relative to the last time the callback was
invoke.  However, if C<hard> is false the new timeout will be
calculated relative to the current time (this is the default).

=item io

Extra attributes: fd => $fd, poll => 'rwe', got => 'rwet',
[timeout => $seconds, hard => $bool]

The callback is invoked when the file descriptor, C<fd>, has data to
be read, written, or pending exceptions.  C<fd> can be a GLOB, an
IO::Handle object, or a file number (file descriptor).

Note that it is your option whether to have multiple watchers per file
handle or to use a single watcher for all event conditions.

=item signal

Extra attribute: signal => $str

=item semaphore

Not yet implemented.

=item msg

Not yet implemented.

=back
    
=head2 ATTRIBUTES

The following attributes currently have a meaning:

=over 4

=item after => $seconds

=item async => $bool

For use in the constructor to specify a priority of -1.

=item at => $time

=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 clump => $bool

A watcher must somehow record if an event occurs many times before any
processing can take place.  Currently there are two choice.  If clump
is false then a new event will be generated for each occurance.  On
the other hand, if clump is true then each event occurance will
increment C<hits>.  Clumping is slightly more efficient than not
clumping.

=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

=item flags => $bits
 
The C<flag> attribute encodes information about the state of an
event.  [XXX Fill in exact bits] [DEPRECATED?]

=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
expression of interest.

=item hard => $bool

Determines how repeating timers 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 hits => $int

A watcher increments C<hits> every time it registers an event.  This
is usually only relevant if C<clump> is enabled.

=item interval => $seconds

How long between repeating timeouts.

=item level => $priority

=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 the callback.  If the
callback uses more time then it is aborted.  Defaults to 1 sec.  This
feature is normally disabled.  See L<Event::Stats>.

=item min => $seconds

Enforce a minimum number of seconds between triggering events.

=item nice => $int

For use in constructors to specify the offset from the default
priority.  All watchers have a default priority. See
${"Event::${type}::DefaultPriority"}.

=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);

=item prio => $int

Priority is used to sort the event queue.  Meaningful priorities range
from -1 to 6 inclusive.  Lower numbers mean higher priority (-1 is the
highest priority and 6 is the lowest).  When multiple events happen,
the events with the highest priority are serviced first.

A negative priority indicates that the callback should be invoked
immediately upon event occurance.  Use this with caution.  While it
may seem advantageous to use negative priorities, they bypass the
whole point of having an event queue.

Event constructors also accept C<nice> as an offset from the default
priority.  Each type of event has a default priority. Most normal
watchers default to C<PRIO_NORMAL> and most asyncronous watchers
default to C<PRIO_HIGH>. Default priorities are stored in
${"Event::${type}::DefaultPriority"}.

=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 running => $int

Zero if the callback is not running.  Otherwise, the number of levels
that the callback has been entered.  This can be greater than one if
a C<reentrant> callback invokes C<loop> (or to a lesser extent C<sweep>).

=item signal => $str

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

=item suspend => $bool

Don't look for events any more.  Running events are allowed to
complete but pending events are cancelled.  Suspend should be
considered a debugging tool.  If you actually want to stop a watcher,
use the C<stop> method.

=item timeout => $seconds

The number of seconds before a watcher times out.

=item var => $ref

A reference to the variable being watched.

=back

=head2 Customization and Exceptions

The bulk of Event's implementation is in C for B<maximum>
performance. However, a broad range of customization hooks are
available.

=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::Eval

Strictly for debugging.  Do not enable this unless you know what you
are doing.

=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:
 
  $Event::DIED->($event, $@);
 
The default hook uses C<warn> to print the exception.  After the DIED
handler returns, event processing continues as if nothing happened.
If you'd like to see more detailed output you can use the verbose
handler (below) or write your own.

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

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

The C<add_hooks> method allows customization at key points in the
optimized event processing core.  Currently support hooks are detailed
below:

  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 L<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.  Much higher
performance can be acheived 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 simultaineously.  I hope this sounds dangerous!  It
is!  Threads can introduce maddeningly complicated and hard to debug
syncronization 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.

=head1 WHAT ABOUT NON-PREEMPTIVE THREADS?

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

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.

=head1 BUGS

The meaning of $io->timeout(0) might change.  Use C<undef> to unset
the timeout.

=head2 WHY MICROSOFT WINDOWS MIGHT BE FASTER THAN UNIX

  http://www.usenix.org/events/usenix99/full_papers/banga/banga_html/index.html

=head1 ALSO SEE

L<Time::HiRes>, L<Time::Warp>, and L<NetServer::ProcessTop>.

=head1 SUPPORT

If you have insights or complaints then please subscribe to the
mailing list!  Send email to:

  majordomo@perl.org

The body of your message should read: 

  subscribe perl-loop

This list is archived at

  http://www.xray.mpe.mpg.de/mailing-lists/perl-loop/

Thanks!

=head1 AUTHORS

Joshua N. Pritikin E<lt>F<bitset@mindspring.com>E<gt>

Initial 0.01 implementation by Graham Barr
E<lt>F<gbarr@pobox.com>E<gt>.  Also, contributions from:

 Gisle Aas E<lt>F<gisle@aas.no>E<gt>
 E<lt>F<jan.dubois@ibm.net>E<gt> (Win32)
 E<lt>F<Matija.Grabnar@arnes.si>E<gt> (File::Tail)
 Nick Ing-Simmons E<lt>F<nick@ni-s.u-net.com>E<gt> (Tk)
 Mark Mielke E<lt>F<Mark.Mielke.markm@nt.com>E<gt>
 Sarathy E<lt>F<gsar@engin.umich.edu>E<gt>

=head1 COPYRIGHT

Copyright © 1997-1999 Joshua Nathaniel Pritikin & Graham Barr.  All
rights reserved.  This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.

=cut
