view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        using this from a module, never require a blocking wait*. Instead,
        let the caller decide whether the call will block or not (for
        example, by coupling condition variables with some kind of request
        results and supporting callbacks so the caller knows that getting
        the result will not block, while still supporting blocking waits if
        the caller so desires).

        You can ensure that "->recv" never blocks by setting a callback and
        only calling "->recv" from within that callback (or at a later
        time). This will work even when the event loop does not support
        blocking waits otherwise.

    $bool = $cv->ready
        Returns true when the condition is "true", i.e. whether "send" or
        "croak" have been called.

    $cb = $cv->cb ($cb->($cv))
        This is a mutator function that returns the callback set (or "undef"
        if not) and optionally replaces it before doing so.

        The callback will be called when the condition becomes "true", i.e.
        when "send" or "croak" are called, with the only argument being the
        condition variable itself. If the condition is already true, the
        callback is called immediately when it is set. Calling "recv" inside
        the callback or at any later time is guaranteed not to block.

        Additionally, when the callback is invoked, it is also removed from
        the condvar (reset to "undef"), so the condvar does not keep a
        reference to the callback after invocation.

SUPPORTED EVENT LOOPS/BACKENDS
    The following backend classes are part of the AnyEvent distribution
    (every class has its own manpage):

    Backends that are autoprobed when no other event loop can be found.
        EV is the preferred backend when no other event loop seems to be in
        use. If EV is not installed, then AnyEvent will fall back to its own
        pure-perl implementation, which is available everywhere as it comes
        with AnyEvent itself.

           AnyEvent::Impl::EV        based on EV (interface to libev, best choice).
           AnyEvent::Impl::Perl      pure-perl AnyEvent::Loop, fast and portable.

    Backends that are transparently being picked up when they are used.
        These will be used if they are already loaded when the first watcher
        is created, in which case it is assumed that the application is
        using them. This means that AnyEvent will automatically pick the
        right backend when the main program loads an event module before
        anything starts to create watchers. Nothing special needs to be done
        by the main program.

           AnyEvent::Impl::Event     based on Event, very stable, few glitches.
           AnyEvent::Impl::Glib      based on Glib, slow but very stable.
           AnyEvent::Impl::Tk        based on Tk, very broken.
           AnyEvent::Impl::UV        based on UV, innovated square wheels.
           AnyEvent::Impl::EventLib  based on Event::Lib, leaks memory and worse.
           AnyEvent::Impl::POE       based on POE, very slow, some limitations.
           AnyEvent::Impl::Irssi     used when running within irssi.
           AnyEvent::Impl::IOAsync   based on IO::Async.
           AnyEvent::Impl::Cocoa     based on Cocoa::EventLoop.
           AnyEvent::Impl::FLTK      based on FLTK (fltk 2 binding).

    Backends with special needs.
        Qt requires the Qt::Application to be instantiated first, but will
        otherwise be picked up automatically. As long as the main program
        instantiates the application before any AnyEvent watchers are
        created, everything should just work.

           AnyEvent::Impl::Qt        based on Qt.

    Event loops that are indirectly supported via other backends.
        Some event loops can be supported via other modules:

        There is no direct support for WxWidgets (Wx) or Prima.

        WxWidgets has no support for watching file handles. However, you can
        use WxWidgets through the POE adaptor, as POE has a Wx backend that
        simply polls 20 times per second, which was considered to be too
        horrible to even consider for AnyEvent.

        Prima is not supported as nobody seems to be using it, but it has a
        POE backend, so it can be supported through POE.

        AnyEvent knows about both Prima and Wx, however, and will try to
        load POE when detecting them, in the hope that POE will pick them
        up, in which case everything will be automatic.

    Known event loops outside the AnyEvent distribution
        The following event loops or programs support AnyEvent by providing
        their own AnyEvent backend. They will be picked up automatically.

           urxvt::anyevent           available to rxvt-unicode extensions

GLOBAL VARIABLES AND FUNCTIONS
    These are not normally required to use AnyEvent, but can be useful to
    write AnyEvent extension modules.

    $AnyEvent::MODEL
        Contains "undef" until the first watcher is being created, before
        the backend has been autodetected.

        Afterwards it contains the event model that is being used, which is
        the name of the Perl class implementing the model. This class is
        usually one of the "AnyEvent::Impl::xxx" modules, but can be any
        other class in the case AnyEvent has been extended at runtime (e.g.
        in *rxvt-unicode* it will be "urxvt::anyevent").

    AnyEvent::detect
        Returns $AnyEvent::MODEL, forcing autodetection of the event model
        if necessary. You should only call this function right before you
        would have created an AnyEvent watcher anyway, that is, as late as
        possible at runtime, and not e.g. during initialisation of your
        module.

        The effect of calling this function is as if a watcher had been
        created (specifically, actions that happen "when the first watcher
        is created" happen when calling detetc as well).

        If you need to do some initialisation before AnyEvent watchers are
        created, use "post_detect".

README  view on Meta::CPAN

        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
        programs can be very useful, however.

    "PERL_ANYEVENT_DEBUG_SHELL"
        If this env variable is nonempty, then its contents will be
        interpreted by "AnyEvent::Socket::parse_hostport" and
        "AnyEvent::Debug::shell" (after replacing every occurance of $$ by
        the process pid). The shell object is saved in
        $AnyEvent::Debug::SHELL.

        This happens when the first watcher is created.

        For example, to bind a debug shell on a unix domain socket in
        /tmp/debug<pid>.sock, you could use this:

           PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
           # connect with e.g.: socat readline /tmp/debug123.sock

        Or to bind to tcp port 4545 on localhost:

           PERL_ANYEVENT_DEBUG_SHELL=127.0.0.1:4545 perlprog
           # connect with e.g.: telnet localhost 4545

        Note that creating sockets in /tmp or on localhost is very unsafe on
        multiuser systems.

    "PERL_ANYEVENT_DEBUG_WRAP"
        Can be set to 0, 1 or 2 and enables wrapping of all watchers for
        debugging purposes. See "AnyEvent::Debug::wrap" for details.

    "PERL_ANYEVENT_MODEL"
        This can be used to specify the event model to be used by AnyEvent,
        before auto detection and -probing kicks in.

        It normally is a string consisting entirely of ASCII letters (e.g.
        "EV" or "IOAsync"). The string "AnyEvent::Impl::" gets prepended and
        the resulting module name is loaded and - if the load was successful
        - used as event model backend. If it fails to load then AnyEvent
        will proceed with auto detection and -probing.

        If the string ends with "::" instead (e.g. "AnyEvent::Impl::EV::")
        then nothing gets prepended and the module name is used as-is (hint:
        "::" at the end of a string designates a module name and quotes it
        appropriately).

        For example, to force the pure perl model (AnyEvent::Loop::Perl) you
        could start your program like this:

           PERL_ANYEVENT_MODEL=Perl perl ...

    "PERL_ANYEVENT_IO_MODEL"
        The current file I/O model - see AnyEvent::IO for more info.

        At the moment, only "Perl" (small, pure-perl, synchronous) and
        "IOAIO" (truly asynchronous) are supported. The default is "IOAIO"
        if AnyEvent::AIO can be loaded, otherwise it is "Perl".

    "PERL_ANYEVENT_PROTOCOLS"
        Used by both AnyEvent::DNS and AnyEvent::Socket to determine
        preferences for IPv4 or IPv6. The default is unspecified (and might
        change, or be the result of auto probing).

        Must be set to a comma-separated list of protocols or address
        families, current supported: "ipv4" and "ipv6". Only protocols
        mentioned will be used, and preference will be given to protocols
        mentioned earlier in the list.

        This variable can effectively be used for denial-of-service attacks
        against local programs (e.g. when setuid), although the impact is
        likely small, as the program has to handle connection and other
        failures anyways.

        Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
        IPv6, but support both and try to use both.
        "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
        resolve or contact IPv6 addresses.
        "PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4" support either IPv4 or IPv6, but
        prefer IPv6 over IPv4.