view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        you:

           async {
              Coro::AnyEvent::sleep 5; # creates a 5s timer and waits for it
              print "5 seconds later!\n";

              Coro::AnyEvent::readable *STDIN; # uses an I/O watcher
              my $line = <STDIN>; # works for ttys

              AnyEvent::HTTP::http_get "url", Coro::rouse_cb;
              my ($body, $hdr) = Coro::rouse_wait;
           };

SIMPLIFIED AE API
    Starting with version 5.0, AnyEvent officially supports a second, much
    simpler, API that is designed to reduce the calling, typing and memory
    overhead by using function call syntax and a fixed number of parameters.

    See the AE manpage for details.

ERROR AND EXCEPTION HANDLING
    In general, AnyEvent does not do any error handling - it relies on the
    caller to do that if required. The AnyEvent::Strict module (see also the
    "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
    checking of all AnyEvent methods, however, which is highly useful during
    development.

    As for exception handling (i.e. runtime errors and exceptions thrown
    while executing a callback), this is not only highly event-loop
    specific, but also not in any way wrapped by this module, as this is the
    job of the main program.

    The pure perl event loop simply re-throws the exception (usually within
    "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
    Glib uses "install_exception_handler" and so on.

ENVIRONMENT VARIABLES
    AnyEvent supports a number of environment variables that tune the
    runtime behaviour. They are usually evaluated when AnyEvent is loaded,
    initialised, or a submodule that uses them is loaded. Many of them also
    cause AnyEvent to load additional modules - for example,
    "PERL_ANYEVENT_DEBUG_WRAP" causes the AnyEvent::Debug module to be
    loaded.

    All the environment variables documented here start with
    "PERL_ANYEVENT_", which is what AnyEvent considers its own namespace.
    Other modules are encouraged (but by no means required) to use
    "PERL_ANYEVENT_SUBMODULE" if they have registered the
    AnyEvent::Submodule namespace on CPAN, for any submodule. For example,
    AnyEvent::HTTP could be expected to use "PERL_ANYEVENT_HTTP_PROXY" (it
    should not access env variables starting with "AE_", see below).

    All variables can also be set via the "AE_" prefix, that is, instead of
    setting "PERL_ANYEVENT_VERBOSE" you can also set "AE_VERBOSE". In case
    there is a clash btween anyevent and another program that uses
    "AE_something" you can set the corresponding "PERL_ANYEVENT_something"
    variable to the empty string, as those variables take precedence.

    When AnyEvent is first loaded, it copies all "AE_xxx" env variables to
    their "PERL_ANYEVENT_xxx" counterpart unless that variable already
    exists. If taint mode is on, then AnyEvent will remove *all* environment
    variables starting with "PERL_ANYEVENT_" from %ENV (or replace them with
    "undef" or the empty string, if the corresaponding "AE_" variable is
    set).

    The exact algorithm is currently:

       1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
       2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
       3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.

    This ensures that child processes will not see the "AE_" variables.

    The following environment variables are currently known to AnyEvent:

    "PERL_ANYEVENT_VERBOSE"
        By default, AnyEvent will log messages with loglevel 4 ("error") or
        higher (see AnyEvent::Log). You can set this environment variable to
        a numerical loglevel to make AnyEvent more (or less) talkative.

        If you want to do more than just set the global logging level you
        should have a look at "PERL_ANYEVENT_LOG", which allows much more
        complex specifications.

        When set to 0 ("off"), then no messages whatsoever will be logged
        with everything else at defaults.

        When set to 5 or higher ("warn"), AnyEvent warns about unexpected
        conditions, such as not being able to load the event model specified
        by "PERL_ANYEVENT_MODEL", or a guard callback throwing an exception
        - this is the minimum recommended level for use during development.

        When set to 7 or higher (info), AnyEvent reports which event model
        it chooses.

        When set to 8 or higher (debug), then AnyEvent will report extra
        information on which optional modules it loads and how it implements
        certain features.

    "PERL_ANYEVENT_LOG"
        Accepts rather complex logging specifications. For example, you
        could log all "debug" messages of some module to stderr, warnings
        and above to stderr, and errors and above to syslog, with:

           PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog

        For the rather extensive details, see AnyEvent::Log.

        This variable is evaluated when AnyEvent (or AnyEvent::Log) is
        loaded, so will take effect even before AnyEvent has initialised
        itself.

        Note that specifying this environment variable causes the
        AnyEvent::Log module to be loaded, while "PERL_ANYEVENT_VERBOSE"
        does not, so only using the latter saves a few hundred kB of memory
        unless a module explicitly needs the extra features of
        AnyEvent::Log.

    "PERL_ANYEVENT_STRICT"
        AnyEvent does not do much argument checking by default, as thorough
        argument checking is very costly. Setting this variable to a true
        value will cause AnyEvent to load "AnyEvent::Strict" and then to
        thoroughly check the arguments passed to most method calls. If it
        finds any problems, it will croak.

        In other words, enables "strict" mode.

        Unlike "use strict" (or its modern cousin, "use common::sense", it
        is definitely recommended to keep it off in production. Keeping
        "PERL_ANYEVENT_STRICT=1" in your environment while developing

README  view on Meta::CPAN

    fork in one way or another. Only EV is fully fork-aware and ensures that
    you continue event-processing in both parent and child (or both, if you
    know what you are doing).

    This means that, in general, you cannot fork and do event processing in
    the child if the event library was initialised before the fork (which
    usually happens when the first AnyEvent watcher is created, or the
    library is loaded).

    If you have to fork, you must either do so *before* creating your first
    watcher OR you must not use AnyEvent at all in the child OR you must do
    something completely out of the scope of AnyEvent (see below).

    The problem of doing event processing in the parent *and* the child is
    much more complicated: even for backends that *are* fork-aware or
    fork-safe, their behaviour is not usually what you want: fork clones all
    watchers, that means all timers, I/O watchers etc. are active in both
    parent and child, which is almost never what you want. Using "exec" to
    start worker children from some kind of manage prrocess is usually
    preferred, because it is much easier and cleaner, at the expense of
    having to have another binary.

    In addition to logical problems with fork, there are also implementation
    problems. For example, on POSIX systems, you cannot fork at all in Perl
    code if a thread (I am talking of pthreads here) was ever created in the
    process, and this is just the tip of the iceberg. In general, using fork
    from Perl is difficult, and attempting to use fork without an exec to
    implement some kind of parallel processing is almost certainly doomed.

    To safely fork and exec, you should use a module such as Proc::FastSpawn
    that let's you safely fork and exec new processes.

    If you want to do multiprocessing using processes, you can look at the
    AnyEvent::Fork module (and some related modules such as
    AnyEvent::Fork::RPC, AnyEvent::Fork::Pool and AnyEvent::Fork::Remote).
    This module allows you to safely create subprocesses without any
    limitations - you can use X11 toolkits or AnyEvent in the children
    created by AnyEvent::Fork safely and without any special precautions.

SECURITY CONSIDERATIONS
    AnyEvent can be forced to load any event model via
    $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
    to execute arbitrary code or directly gain access, it can easily be used
    to make the program hang or malfunction in subtle ways, as AnyEvent
    watchers will not be active when the program uses a different event
    model than specified in the variable.

    You can make AnyEvent completely ignore this variable by deleting it
    before the first watcher gets created, e.g. with a "BEGIN" block:

       BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
  
       use AnyEvent;

    Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
    be used to probe what backend is used and gain other information (which
    is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
    and $ENV{PERL_ANYEVENT_STRICT}.

    Note that AnyEvent will remove *all* environment variables starting with
    "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
    enabled.

BUGS
    Perl 5.8 has numerous memleaks that sometimes hit this module and are
    hard to work around. If you suffer from memleaks, first upgrade to Perl
    5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
    annoying memleaks, such as leaking on "map" and "grep" but it is usually
    not as pronounced).

SEE ALSO
    Tutorial/Introduction: AnyEvent::Intro.

    FAQ: AnyEvent::FAQ.

    Utility functions: AnyEvent::Util (misc. grab-bag), AnyEvent::Log
    (simply logging).

    Development/Debugging: AnyEvent::Strict (stricter checking),
    AnyEvent::Debug (interactive shell, watcher tracing).

    Supported event modules: AnyEvent::Loop, EV, EV::Glib, Glib::EV, Event,
    Glib::Event, Glib, Tk, Event::Lib, Qt, POE, FLTK, Cocoa::EventLoop, UV.

    Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
    AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
    AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
    AnyEvent::Impl::IOAsync, AnyEvent::Impl::Irssi, AnyEvent::Impl::FLTK,
    AnyEvent::Impl::Cocoa, AnyEvent::Impl::UV.

    Non-blocking handles, pipes, stream sockets, TCP clients and servers:
    AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.

    Asynchronous File I/O: AnyEvent::IO.

    Asynchronous DNS: AnyEvent::DNS.

    Thread support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event.

    Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::IRC,
    AnyEvent::HTTP.

AUTHOR
       Marc Lehmann <schmorp@schmorp.de>
       http://anyevent.schmorp.de