can get whatever behaviour you want with any event loop, by taking the
difference between C<< AnyEvent->time >> and C<< AnyEvent->now >> into
account.

=back

=head2 SIGNAL WATCHERS

You can watch for signals using a signal watcher, C<signal> is the signal
I<name> without any C<SIG> prefix, C<cb> is the Perl callback to
be invoked whenever a signal occurs.

Although the callback might get passed parameters, their value and
presence is undefined and you cannot rely on them. Portable AnyEvent
callbacks cannot use arguments passed to signal watcher callbacks.

Multiple signal occurrences can be clumped together into one callback
invocation, and callback invocation will be synchronous. Synchronous means
that it might take a while until the signal gets handled by the process,
but it is guaranteed not to interrupt any other callbacks.

The main advantage of using these watchers is that you can share a signal
between multiple watchers.

This watcher might use C<%SIG>, so programs overwriting those signals
directly will likely not work correctly.

Example: exit on SIGINT

   my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });

=head2 CHILD PROCESS WATCHERS

You can also watch on a child process exit and catch its exit status.

The child process is specified by the C<pid> argument (if set to C<0>, it
watches for any child process exit). The watcher will trigger as often
as status change for the child are received. This works by installing a
signal handler for C<SIGCHLD>. The callback will be called with the pid
and exit status (as returned by waitpid), so unlike other watcher types,
you I<can> rely on child watcher callback arguments.

There is a slight catch to child watchers, however: you usually start them
I<after> the child process was created, and this means the process could
have exited already (and no SIGCHLD will be sent anymore).

Not all event models handle this correctly (POE doesn't), but even for
event models that I<do> handle this correctly, they usually need to be
loaded before the process exits (i.e. before you fork in the first place).

This means you cannot create a child watcher as the very first thing in an
AnyEvent program, you I<have> to create at least one watcher before you
C<fork> the child (alternatively, you can call C<AnyEvent::detect>).

Example: fork a process and wait for it

   my $done = AnyEvent->condvar;
  
   my $pid = fork or exit 5;
  
   my $w = AnyEvent->child (
      pid => $pid,
      cb  => sub {
         my ($pid, $status) = @_;
         warn "pid $pid exited with status $status";
         $done->send;
      },
   );
  
   # do something else, then wait for process exit
   $done->recv;

=head2 CONDITION VARIABLES

If you are familiar with some event loops you will know that all of them
require you to run some blocking "loop", "run" or similar function that
will actively watch for new events and call your callbacks.

AnyEvent is different, it expects somebody else to run the event loop and
will only block when necessary (usually when told by the user).

The instrument to do that is called a "condition variable", so called
because they represent a condition that must become true.

Condition variables can be created by calling the C<< AnyEvent->condvar
>> method, usually without arguments. The only argument pair allowed is
C<cb>, which specifies a callback to be called when the condition variable
becomes true.

After creation, the condition variable is "false" until it becomes "true"
by calling the C<send> method (or calling the condition variable as if it
were a callback, read about the caveats in the description for the C<<
->send >> method).

Condition variables are similar to callbacks, except that you can
optionally wait for them. They can also be called merge points - points
in time where multiple outstanding events have been processed. And yet
another way to call them is transactions - each condition variable can be
used to represent a transaction, which finishes at some point and delivers
a result.