=head1 NAME

Event - Event loop processing

=head1 WARNING

B<THIS IS EXPERIMENTAL CODE AND IS LIKELY TO CHANGE A CONSIDERABLE AMOUNT>
B<BEFORE IT IS RELEASED FOR GENERAL USE.>

=head1 SYNOPSIS

    use Event;
    
    # initialize application
    
    my $ret = Event::Loop::Loop();
    
    # and some callback will call
    Event::Loop::exitLoop('ok');


=head1 DESCRIPTION

=head1 EVENTS

The following properties are common to all events.  Each property can
be prepended with a dash (-) or not depending on your preferance.

=over 4

=item callback

Use either a code ref or an array containing an object and the method
to call.

=item priority

A default priority is assigned to each event upon creation.  The
default depends on the type of the event.  A +- offset from the
default can be passed via the C<priority> key.  If the C<priority> is
a negative number the callback will be called immediately, otherwise
it will be pushed onto the event queue.  While it may seem
advantageous to use a negative priorities, it defeats the purpose of
even having an event queue in the first place.

=item now

Events can be queued manually with the C<now> method.  Any C<now>
additional arguments passed to now are forwarded to the event
callback.  You must provide whatever arguments your event handler is
expecting since the C<now> method bypasses the usual dispatch
apparatus.

=item queuing

An event can only be queued once.

=item cancel

Cancelled events are not invoked.

=back

=head1 EVENT TYPES

=over 4

=item idle

    Event->idle(callback => \&idle);

Call C<&idle> when the loop is idle.

=item watchvar

    $e = Event->watchvar(
	variable => \$var,
	callback => \&watcher,
    );

Call C<&watcher> when C<$var> is changed.

When called C<&watcher> will be passed C<$e> as the first argument.

=item timer
    
    $e = Event->timer(
	after    => 10,
	at	  => time + 10,
	interval => 2,
	callback => \&timeout
    );

Call C<&timeout> either after a given delay or at a given time (C<after>
and C<at> are mutually exclusive).  Then optionally call C<&timeout>
at given intervals.

When called C<&timeout> will be passed C<$e> as the first argument,
and the time that the event was triggered as the second argument.  If
C<interval> was not given and C<after> was then C<&timeout> may call
the C<again> method on C<$e> which will cause the event to re-occur,
the time at which the event will re-occur is the value given by
C<after> added to the time the event was triggered.

Due to lags in the event loop, the re-queued timeout may already be in
the past.  If the 'hard' flags was set, the event will be queued for
execution immediately.  Otherwise, the new timeout will be calculated
relative to the current time (this is the default).


=item io

    $e = Event->io(
	handle => $sock,
	events => 'r',
	callback => \&ready
    );

Call C<&ready> when C<$sock> has data to be read.  C<event> takes one
or more of 'r', 'w', or 'e'.  These correspond to read, write, and
exceptional data, respectively.

When called C<&ready> is passed C<$e> as the first argument, C<$handle>
as the second argument and the events that happened as the third argument.
C<&ready> may call the C<cancel> method on C<$e> to stop any future
event handling on C<$handle>

=item signal
    
    $e = Event->signal(
	signal => 'INT',
	callback => \&interrupt
    );

Call C<&interrupt> when an C<INT> signal is received. C<signal> accepts
any signal name except C<CHLD>, see below.

When called C<&interrupt> will be passed C<$e> as the first argument and
the name of the signal as the second. C<&interrupt> amy call the C<cancel>
method on C<$e> to stop any future events being caught.


=item process

    $e = Event->process(
	pid => $pid,
	callback => \&reap
    );

Call C<&reap> when the child process with pid C<$pid> exits.  If
C<$pid> is not given then C<&reap> will be called for any process that
does not have it's own event handler.

When called C<&reap> will be passed C<$e> as the first parameter, the
process id of the child as the second and the exit status of the child
as the third.  C<&reap> may call the C<cancel> method on C<$e> to stop
future process events but this is only of use on event handlers where
C<pid> is not specified.

=back

=head1 CALLBACK ARGUMENTS

The arguments passed to the event callback depends on the type of the
event handler:

  io             $event
  process        $event, $pid, $status
  signal         $event, $name, $count
  timer          $event, $when
  watchvar       $event, $ref

=head1 Event::Loop API

=over 4

=item $Now

Time::HiRes::time() cache for low-accuracy clients.

=item queueEvent

=item doOneEvent

=item Loop

=item exitLoop

=item PRIO_HIGH, PRIO_NORMAL, QUEUES

=back

=head1 A COMMENT ON THE DESIGN

While object-oriented design has gained popularity in recent times,
Event does not follow these ideas as strictly as it might.
Performance cannot be sacrificed for theoretical beauty.  Real beauty
is to balance a solution to the requirements, without elaboration.

=head1 DIRECTION

    # generate an event when we can successfully run an op
    $e = Event->semaphore(
	semaphore => $sem,
	op => $op,
	callback => \&gotit
    );
    
    # generate an event when the msg queue is/is not empty
    $e = Event->msg(
	msg => $msg,
	callback => \&doit
    );
    
=head1 SUPPORT

This extension is discussed on the perl-loop@perl.org mailing list.

=head1 AUTHORS

Graham Barr E<lt>F<gbarr@pobox.com>E<gt>,
Joshua Pritikin E<lt>F<bitset@mindspring.com>E<gt>

=head1 COPYRIGHT

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

=cut
