[ViewVC] Diff of: cvs/AnyEvent/README

Comparing AnyEvent/README (file contents):
Revision 1.47 by root, Mon Jul 20 22:39:57 2009 UTC vs.
Revision 1.50 by root, Sat Aug 1 09:14:54 2009 UTC

 NAME
-    AnyEvent - events independent of event loop implementation
+    AnyEvent - the DBI of event loop programming
-    EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported
+    EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async,
-    event loops.
+    Qt and POE are various supported event loops/environments.
 SYNOPSIS
        use AnyEvent;
        # file descriptor readable
 SUPPORT
     There is a mailinglist for discussing all things AnyEvent, and an IRC
     channel, too.
     See the AnyEvent project page at the Schmorpforge Ta-Sa Software
-    Respository, at <http://anyevent.schmorp.de>, for more info.
+    Repository, at <http://anyevent.schmorp.de>, for more info.
 WHY YOU SHOULD USE THIS MODULE (OR NOT)
     Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
     nowadays. So what is different about AnyEvent?
     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
           warn "read: $input\n";
           undef $w;
        });
   TIME WATCHERS
+       $w = AnyEvent->timer (after => <seconds>, cb => <callback>);
+       $w = AnyEvent->timer (
+          after    => <fractional_seconds>,
+          interval => <fractional_seconds>,
+          cb       => <callback>,
+       );
     You can create a time watcher by calling the "AnyEvent->timer" method
     with the following mandatory arguments:
     "after" specifies after how many seconds (fractional values are
     supported) the callback should be invoked. "cb" is the callback to
         the event loop's idea of "current time".
         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
        my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
    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. AnyEvent will try to do it's best,
+    race-free signal handling in perl, requiring C libraries for this.
-    but in some cases, signals will be delayed. The maximum time a signal
+    AnyEvent will try to do it's best, which means in some cases, signals
-    might be delayed is specified in $AnyEvent::MAX_SIGNAL_LATENCY (default:
+    will be delayed. The maximum time a signal might be delayed is specified
-    10 seconds). This variable can be changed only before the first signal
+    in $AnyEvent::MAX_SIGNAL_LATENCY (default: 10 seconds). This variable
-    watcher is created, and should be left alone otherwise. Higher values
+    can be changed only before the first signal watcher is created, and
+    should be left alone otherwise. This variable determines how often
+    AnyEvent polls for signals (in case a wake-up was missed). Higher values
     will cause fewer spurious wake-ups, which is better for power and CPU
+    saving.
-    saving. All these problems can be avoided by installing the optional
+    All these problems can be avoided by installing the optional
-    Async::Interrupt module. This will not work with inherently broken event
+    Async::Interrupt module, which works with most event loops. It will not
-    loops such as Event or Event::Lib (and not with POE currently, as POE
+    work with inherently broken event loops such as Event or Event::Lib (and
-    does it's own workaround with one-second latency). With those, you just
+    not with POE currently, as POE does it's own workaround with one-second
-    have to suffer the delays.
+    latency). For those, you just have to suffer the delays.
   CHILD PROCESS WATCHERS
+       $w = AnyEvent->child (pid => <process id>, cb => <callback>);
     You can also watch on a child process exit and catch its exit status.
-    The child process is specified by the "pid" argument (if set to 0, it
+    The child process is specified by the "pid" argument (one some backends,
-    watches for any child process exit). The watcher will triggered only
+    using 0 watches for any child process exit, on others this will croak).
-    when the child process has finished and an exit status is available, not
+    The watcher will be triggered only when the child process has finished
-    on any trace events (stopped/continued).
+    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.
        # do something else, then wait for process exit
        $done->recv;
   IDLE WATCHERS
+       $w = AnyEvent->idle (cb => <callback>);
     Sometimes there is a need to do something, but it is not so important to
     do it instantly, but only when there is nothing better to do. This
     "nothing better to do" is usually defined to be "no other events need
     attention by the event loop".
              }
           });
        });
   CONDITION VARIABLES
+       $cv = AnyEvent->condvar;
+       $cv->send (<list>);
+       my @res = $cv->recv;
     If you are familiar with some event loops you will know that all of them
     require you to run some blocking "loop", "run" or similar function that
     will actively watch for new events and call your callbacks.
     AnyEvent is slightly different: it expects somebody else to run the
     $cb = $cv->cb ($cb->($cv))
         This is a mutator function that returns the callback set and
         optionally replaces it before doing so.
-        The callback will be called when the condition becomes "true", i.e.
+        The callback will be called when the condition becomes (or already
-        when "send" or "croak" are called, with the only argument being the
+        was) "true", i.e. when "send" or "croak" are called (or were
-        condition variable itself. Calling "recv" inside the callback or at
+        called), with the only argument being the condition variable itself.
+        Calling "recv" inside the callback or at any later time is
-        any later time is guaranteed not to block.
+        guaranteed not to block.
 SUPPORTED EVENT LOOPS/BACKENDS
     The available backend classes are (every class has its own manpage):
     Backends that are autoprobed when no other event loop can be found.
            AnyEvent::Impl::Glib      based on Glib, slow but very stable.
            AnyEvent::Impl::Tk        based on Tk, very broken.
            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.
     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
         creates and installs the global IO::AIO watcher in a "post_detect"
         block to avoid autodetecting the event module at load time.
         If called in scalar or list context, then it creates and returns an
         object that automatically removes the callback again when it is
+        destroyed (or "undef" when the hook was immediately executed). See
-        destroyed. See Coro::BDB for a case where this is useful.
+        AnyEvent::AIO for a case where this is useful.
+        Example: Create a watcher for the IO::AIO module and store it in
+        $WATCHER. Only do so after the event loop is initialised, though.
+           our WATCHER;
+           my $guard = AnyEvent::post_detect {
+              $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
+           };
+           # the ||= is important in case post_detect immediately runs the block,
+           # as to not clobber the newly-created watcher. assigning both watcher and
+           # post_detect guard to the same variable has the advantage of users being
+           # able to just C<undef $WATCHER> if the watcher causes them grief.
+           $WATCHER ||= $guard;
     @AnyEvent::post_detect
         If there are any code references in this array (you can "push" to it
         before or after loading AnyEvent), then they will called directly
         after the event loop has been chosen.
     Event::Lib, Qt, POE.
     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::IOAsync, Anyevent::Impl::Irssi.
     Non-blocking file handles, sockets, TCP clients and servers:
     AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
     Asynchronous DNS: AnyEvent::DNS.

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing AnyEvent/README (file contents): Revision 1.47 by root, Mon Jul 20 22:39:57 2009 UTC vs. Revision 1.50 by root, Sat Aug 1 09:14:54 2009 UTC

Diff Legend

Comparing AnyEvent/README (file contents):
Revision 1.47 by root, Mon Jul 20 22:39:57 2009 UTC vs.
Revision 1.50 by root, Sat Aug 1 09:14:54 2009 UTC