view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    offering the functionality that is necessary, in as thin as a wrapper as
    technically possible.

    Of course, AnyEvent comes with a big (and fully optional!) toolbox of
    useful functionality, such as an asynchronous DNS resolver, 100%
    non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms
    such as Windows) and lots of real-world knowledge and workarounds for
    platform bugs and differences.

    Now, if you *do want* lots of policy (this can arguably be somewhat
    useful) and you want to force your users to use the one and only event
    model, you should *not* use this module.

DESCRIPTION
    AnyEvent provides a uniform interface to various event loops. This
    allows module authors to use event loop functionality without forcing
    module users to use a specific event loop implementation (since more
    than one event loop cannot coexist peacefully).

    The interface itself is vaguely similar, but not identical to the Event
    module.

    During the first call of any watcher-creation method, the module tries
    to detect the currently loaded event loop by probing whether one of the
    following modules is already loaded: EV, AnyEvent::Loop, Event, Glib,
    Tk, Event::Lib, Qt, POE. The first one found is used. If none are
    detected, the module tries to load the first four modules in the order
    given; but note that if EV is not available, the pure-perl
    AnyEvent::Loop should always work, so the other two are not normally
    tried.

    Because AnyEvent first checks for modules that are already loaded,
    loading an event model explicitly before first using AnyEvent will
    likely make that model the default. For example:

       use Tk;
       use AnyEvent;

       # .. AnyEvent will likely default to Tk

    The *likely* means that, if any module loads another event model and
    starts using it, all bets are off - this case should be very rare
    though, as very few modules hardcode event loops without announcing this
    very loudly.

    The pure-perl implementation of AnyEvent is called "AnyEvent::Loop".
    Like other event modules you can load it explicitly and enjoy the high
    availability of that event loop :)

WATCHERS
    AnyEvent has the central concept of a *watcher*, which is an object that
    stores relevant data for each kind of event you are waiting for, such as
    the callback to call, the file handle to watch, etc.

    These watchers are normal Perl objects with normal Perl lifetime. After
    creating a watcher it will immediately "watch" for events and invoke the
    callback when the event occurs (of course, only when the event model is
    in control).

    Note that callbacks must not permanently change global variables
    potentially in use by the event loop (such as $_ or $[) and that
    callbacks must not "die". The former is good programming practice in
    Perl and the latter stems from the fact that exception handling differs
    widely between event loops.

    To disable a watcher you have to destroy it (e.g. by setting the
    variable you store it in to "undef" or otherwise deleting all references
    to it).

    All watchers are created by calling a method on the "AnyEvent" class.

    Many watchers either are used with "recursion" (repeating timers for
    example), or need to refer to their watcher object in other ways.

    One way to achieve that is this pattern:

       my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
          # you can use $w here, for example to undef it
          undef $w;
       });

    Note that "my $w; $w =" combination. This is necessary because in Perl,
    my variables are only visible after the statement in which they are
    declared.

  I/O WATCHERS
       $w = AnyEvent->io (
          fh   => <filehandle_or_fileno>,
          poll => <"r" or "w">,
          cb   => <callback>,
       );

    You can create an I/O watcher by calling the "AnyEvent->io" method with
    the following mandatory key-value pairs as arguments:

    "fh" is the Perl *file handle* (or a naked file descriptor) to watch for
    events (AnyEvent might or might not keep a reference to this file
    handle). Note that only file handles pointing to things for which
    non-blocking operation makes sense are allowed. This includes sockets,
    most character devices, pipes, fifos and so on, but not for example
    files or block devices.

    "poll" must be a string that is either "r" or "w", which creates a
    watcher waiting for "r"eadable or "w"ritable events, respectively.

    "cb" is the callback to invoke each time the file handle becomes ready.

    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 I/O watcher callbacks.

    The I/O watcher might use the underlying file descriptor or a copy of
    it. You must not close a file handle as long as any watcher is active on
    the underlying file descriptor.

    Some event loops issue spurious readiness notifications, so you should
    always use non-blocking calls when reading/writing from/to your file
    handles.

    Example: wait for readability of STDIN, then read a line and disable the
    watcher.