view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    invoke in that case.

    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 time watcher callbacks.

    The callback will normally be invoked only once. If you specify another
    parameter, "interval", as a strictly positive number (> 0), then the
    callback will be invoked regularly at that interval (in fractional
    seconds) after the first invocation. If "interval" is specified with a
    false value, then it is treated as if it were not specified at all.

    The callback will be rescheduled before invoking the callback, but no
    attempt is made to avoid timer drift in most backends, so the interval
    is only approximate.

    Example: fire an event after 7.7 seconds.

       my $w = AnyEvent->timer (after => 7.7, cb => sub {
          warn "timeout\n";
       });

       # to cancel the timer:
       undef $w;

    Example 2: fire an event after 0.5 seconds, then roughly every second.

       my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
          warn "timeout\n";
       });

   TIMING ISSUES
    There are two ways to handle timers: based on real time (relative, "fire
    in 10 seconds") and based on wallclock time (absolute, "fire at 12
    o'clock").

    While most event loops expect timers to specified in a relative way,
    they use absolute time internally. This makes a difference when your
    clock "jumps", for example, when ntp decides to set your clock backwards
    from the wrong date of 2014-01-01 to 2008-01-01, a watcher that is
    supposed to fire "after a second" might actually take six years to
    finally fire.

    AnyEvent cannot compensate for this. The only event loop that is
    conscious of these issues is EV, which offers both relative (ev_timer,
    based on true relative time) and absolute (ev_periodic, based on
    wallclock time) timers.

    AnyEvent always prefers relative timers, if available, matching the
    AnyEvent API.

    AnyEvent has two additional methods that return the "current time":

    AnyEvent->time
        This returns the "current wallclock time" as a fractional number of
        seconds since the Epoch (the same thing as "time" or
        "Time::HiRes::time" return, and the result is guaranteed to be
        compatible with those).

        It progresses independently of any event loop processing, i.e. each
        call will check the system clock, which usually gets updated
        frequently.

    AnyEvent->now
        This also returns the "current wallclock time", but unlike "time",
        above, this value might change only once per event loop iteration,
        depending on the event loop (most return the same time as "time",
        above). This is the time that AnyEvent's timers get scheduled
        against.

        *In almost all cases (in all cases if you don't care), this is the
        function to call when you want to know the current time.*

        This function is also often faster then "AnyEvent->time", and thus
        the preferred method if you want some timestamp (for example,
        AnyEvent::Handle uses this to update its activity timeouts).

        The rest of this section is only of relevance if you try to be very
        exact with your timing; you can skip it without a bad conscience.

        For a practical example of when these times differ, consider
        Event::Lib and EV and the following set-up:

        The event loop is running and has just invoked one of your callbacks
        at time=500 (assume no other callbacks delay processing). In your
        callback, you wait a second by executing "sleep 1" (blocking the
        process for a second) and then (at time=501) you create a relative
        timer that fires after three seconds.

        With Event::Lib, "AnyEvent->time" and "AnyEvent->now" will both
        return 501, because that is the current time, and the timer will be
        scheduled to fire at time=504 (501 + 3).

        With EV, "AnyEvent->time" returns 501 (as that is the current time),
        but "AnyEvent->now" returns 500, as that is the time the last event
        processing phase started. With EV, your timer gets scheduled to run
        at time=503 (500 + 3).

        In one sense, Event::Lib is more exact, as it uses the current time
        regardless of any delays introduced by event processing. However,
        most callbacks do not expect large delays in processing, so this
        causes a higher drift (and a lot more system calls to get the
        current time).

        In another sense, EV is more exact, as your timer will be scheduled
        at the same time, regardless of how long event processing actually
        took.

        In either case, if you care (and in most cases, you don't), then you
        can get whatever behaviour you want with any event loop, by taking
        the difference between "AnyEvent->time" and "AnyEvent->now" into
        account.

    AnyEvent->now_update
        Some event loops (such as EV or AnyEvent::Loop) cache the current
        time for each loop iteration (see the discussion of AnyEvent->now,
        above).

        When a callback runs for a long time (or when the process sleeps),
        then this "current" time will differ substantially from the real
        time, which might affect timers and time-outs.

README  view on Meta::CPAN

        override this delay with this environment variable (or by setting
        the $AnyEvent::MAX_SIGNAL_LATENCY variable before creating signal
        watchers).

        Lower values increase CPU (and energy) usage, higher values can
        introduce long delays when reaping children or waiting for signals.

        The AnyEvent::Async module, if available, will be used to avoid this
        polling (with most event loops).

    "PERL_ANYEVENT_RESOLV_CONF"
        The absolute path to a resolv.conf-style file to use instead of
        /etc/resolv.conf (or the OS-specific configuration) in the default
        resolver, or the empty string to select the default configuration.

    "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH".
        When neither "ca_file" nor "ca_path" was specified during
        AnyEvent::TLS context creation, and either of these environment
        variables are nonempty, they will be used to specify CA certificate
        locations instead of a system-dependent default.

    "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT"
        When these are set to 1, then the respective modules are not loaded.
        Mostly good for testing AnyEvent itself.

SUPPLYING YOUR OWN EVENT MODEL INTERFACE
    This is an advanced topic that you do not normally need to use AnyEvent
    in a module. This section is only of use to event loop authors who want
    to provide AnyEvent compatibility.

    If you need to support another event library which isn't directly
    supported by AnyEvent, you can supply your own interface to it by
    pushing, before the first watcher gets created, the package name of the
    event module and the package name of the interface to use onto
    @AnyEvent::REGISTRY. You can do that before and even without loading
    AnyEvent, so it is reasonably cheap.

    Example:

       push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];

    This tells AnyEvent to (literally) use the "urxvt::anyevent::"
    package/class when it finds the "urxvt" package/module is already
    loaded.

    When AnyEvent is loaded and asked to find a suitable event model, it
    will first check for the presence of urxvt by trying to "use" the
    "urxvt::anyevent" module.

    The class should provide implementations for all watcher types. See
    AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
    so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
    the sources.

    If you don't provide "signal" and "child" watchers than AnyEvent will
    provide suitable (hopefully) replacements.

    The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
    terminal emulator uses the above line as-is. An interface isn't included
    in AnyEvent because it doesn't make sense outside the embedded
    interpreter inside *rxvt-unicode*, and it is updated and maintained as
    part of the *rxvt-unicode* distribution.

    *rxvt-unicode* also cheats a bit by not providing blocking access to
    condition variables: code blocking while waiting for a condition will
    "die". This still works with most modules/usages, and blocking calls
    must not be done in an interactive application, so it makes sense.

EXAMPLE PROGRAM
    The following program uses an I/O watcher to read data from STDIN, a
    timer to display a message once per second, and a condition variable to
    quit the program when the user enters quit:

       use AnyEvent;

       my $cv = AnyEvent->condvar;

       my $io_watcher = AnyEvent->io (
          fh   => \*STDIN,
          poll => 'r',
          cb   => sub {
             warn "io event <$_[0]>\n";   # will always output <r>
             chomp (my $input = <STDIN>); # read a line
             warn "read: $input\n";       # output what has been read
             $cv->send if $input =~ /^q/i; # quit program if /^q/i
          },
       );

       my $time_watcher = AnyEvent->timer (after => 1, interval => 1, cb => sub {
          warn "timeout\n"; # print 'timeout' at most every second
       });

       $cv->recv; # wait until user enters /^q/i

REAL-WORLD EXAMPLE
    Consider the Net::FCP module. It features (among others) the following
    API calls, which are to freenet what HTTP GET requests are to http:

       my $data = $fcp->client_get ($url); # blocks

       my $transaction = $fcp->txn_client_get ($url); # does not block
       $transaction->cb ( sub { ... } ); # set optional result callback
       my $data = $transaction->result; # possibly blocks

    The "client_get" method works like "LWP::Simple::get": it requests the
    given URL and waits till the data has arrived. It is defined to be:

       sub client_get { $_[0]->txn_client_get ($_[1])->result }

    And in fact is automatically generated. This is the blocking API of
    Net::FCP, and it works as simple as in any other, similar, module.

    More complicated is "txn_client_get": It only creates a transaction
    (completion, result, ...) object and initiates the transaction.

       my $txn = bless { }, Net::FCP::Txn::;

    It also creates a condition variable that is used to signal the
    completion of the request:

       $txn->{finished} = AnyAvent->condvar;