view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        then this "current" time will differ substantially from the real
        time, which might affect timers and time-outs.

        When this is the case, you can call this method, which will update
        the event loop's idea of "current time".

        A typical example would be a script in a web server (e.g.
        "mod_perl") - when mod_perl executes the script, then the event loop
        will have the wrong idea about the "current time" (being potentially
        far in the past, when the script ran the last time). In that case
        you should arrange a call to "AnyEvent->now_update" each time the
        web server process wakes up again (e.g. at the start of your script,
        or in a handler).

        Note that updating the time *might* cause some events to be handled.

  SIGNAL WATCHERS
       $w = AnyEvent->signal (signal => <uppercase_signal_name>, cb => <callback>);

    You can watch for signals using a signal watcher, "signal" is the signal
    *name* in uppercase and without any "SIG" prefix, "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, and AnyEvent will ensure that signals
    will not interrupt your program at bad times.

    This watcher might use %SIG (depending on the event loop used), 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 });

   Restart Behaviour
    While restart behaviour is up to the event loop implementation, most
    will not restart syscalls (that includes Async::Interrupt and AnyEvent's
    pure perl implementation).

   Safe/Unsafe Signals
    Perl signals can be either "safe" (synchronous to opcode handling) or
    "unsafe" (asynchronous) - the former might delay signal delivery
    indefinitely, the latter might corrupt your memory.

    AnyEvent signal handlers are, in addition, synchronous to the event
    loop, i.e. they will not interrupt your running perl program but will
    only be called as part of the normal event handling (just like timer,
    I/O etc. callbacks, too).

   Signal Races, Delays and Workarounds
    Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
    callbacks to signals in a generic way, which is a pity, as you cannot do
    race-free signal handling in perl, requiring C libraries for this.
    AnyEvent will try to do its best, which means in some cases, signals
    will be delayed. The maximum time a signal might be delayed is 10
    seconds by default, but can be overriden via
    $ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY} or $AnyEvent::MAX_SIGNAL_LATENCY
    - see the "ENVIRONMENT VARIABLES" section for details.

    All these problems can be avoided by installing the optional
    Async::Interrupt module, which works with most event loops. It will not
    work with inherently broken event loops such as Event or Event::Lib (and
    not with POE currently). For those, you just have to suffer the delays.

  CHILD PROCESS WATCHERS
       $w = AnyEvent->child (pid => <process id>, cb => <callback>);

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

    The child process is specified by the "pid" argument (on some backends,
    using 0 watches for any child process exit, on others this will croak).
    The watcher will be triggered only when the child process has finished
    and an exit status is available, not on any trace events
    (stopped/continued).

    The callback will be called with the pid and exit status (as returned by
    waitpid), so unlike other watcher types, you *can* rely on child watcher
    callback arguments.

    This watcher type works by installing a signal handler for "SIGCHLD",
    and since it cannot be shared, nothing else should use SIGCHLD or reap
    random child processes (waiting for specific child processes, e.g.
    inside "system", is just fine).

    There is a slight catch to child watchers, however: you usually start
    them *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 (neither POE nor IO::Async
    do, see their AnyEvent::Impl manpages for details), but even for event
    models that *do* handle this correctly, they usually need to be loaded
    before the process exits (i.e. before you fork in the first place).
    AnyEvent's pure perl event loop handles all cases correctly regardless
    of when you start the watcher.

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

    As most event loops do not support waiting for child events, they will
    be emulated by AnyEvent in most cases, in which case the latency and
    race problems mentioned in the description of signal watchers apply.

    Example: fork a process and wait for it

       my $done = AnyEvent->condvar;
  
       # this forks and immediately calls exit in the child. this
       # normally has all sorts of bad consequences for your parent,
       # so take this as an example only. always fork and exec,
       # or call POSIX::_exit, in real code.