[ViewVC] Diff of: cvs/AnyEvent/README

Comparing AnyEvent/README (file contents):
Revision 1.40 by root, Tue Jun 23 23:37:32 2009 UTC vs.
Revision 1.42 by root, Mon Jun 29 21:00:32 2009 UTC

     There is a slight catch to child watchers, however: you usually start
     them *after* the child process was created, and this means the process
     could have exited already (and no SIGCHLD will be sent anymore).
-    Not all event models handle this correctly (POE doesn't), but even for
+    Not all event models handle this correctly (neither POE nor IO::Async
+    do, see their AnyEvent::Impl manpages for details), but even for event
-    event models that *do* handle this correctly, they usually need to be
+    models that *do* handle this correctly, they usually need to be loaded
-    loaded before the process exits (i.e. before you fork in the first
+    before the process exits (i.e. before you fork in the first place).
-    place).
+    AnyEvent's pure perl event loop handles all cases correctly regardless
+    of when you start the watcher.
     This means you cannot create a child watcher as the very first thing in
     an AnyEvent program, you *have* to create at least one watcher before
     you "fork" the child (alternatively, you can call "AnyEvent::detect").
         This can be used to signal any errors to the condition variable
         user/consumer.
     $cv->begin ([group callback])
     $cv->end
-        These two methods are EXPERIMENTAL and MIGHT CHANGE.
         These two methods can be used to combine many transactions/events
         into one. For example, a function that pings many hosts in parallel
         might want to use a condition variable for the whole process.
         Every call to "->begin" will increment a counter, and every call to
         "->end" will decrement it. If the counter reaches 0 in "->end", the
         (last) callback passed to "begin" will be executed. That callback is
         *supposed* to call "->send", but that is not required. If no
         callback was set, "send" will be called without any arguments.
-        Let's clarify this with the ping example:
+        You can think of "$cv->send" giving you an OR condition (one call
+        sends), while "$cv->begin" and "$cv->end" giving you an AND
+        condition (all "begin" calls must be "end"'ed before the condvar
+        sends).
+        Let's start with a simple example: you have two I/O watchers (for
+        example, STDOUT and STDERR for a program), and you want to wait for
+        both streams to close before activating a condvar:
+           my $cv = AnyEvent->condvar;
+           $cv->begin; # first watcher
+           my $w1 = AnyEvent->io (fh => $fh1, cb => sub {
+              defined sysread $fh1, my $buf, 4096
+                 or $cv->end;
+           });
+           $cv->begin; # second watcher
+           my $w2 = AnyEvent->io (fh => $fh2, cb => sub {
+              defined sysread $fh2, my $buf, 4096
+                 or $cv->end;
+           });
+           $cv->recv;
+        This works because for every event source (EOF on file handle),
+        there is one call to "begin", so the condvar waits for all calls to
+        "end" before sending.
+        The ping example mentioned above is slightly more complicated, as
+        the there are results to be passwd back, and the number of tasks
+        that are begung can potentially be zero:
            my $cv = AnyEvent->condvar;
            my %result;
            $cv->begin (sub { $cv->send (\%result) });
         the loop, which serves two important purposes: first, it sets the
         callback to be called once the counter reaches 0, and second, it
         ensures that "send" is called even when "no" hosts are being pinged
         (the loop doesn't execute once).
-        This is the general pattern when you "fan out" into multiple
+        This is the general pattern when you "fan out" into multiple (but
-        subrequests: use an outer "begin"/"end" pair to set the callback and
+        potentially none) subrequests: use an outer "begin"/"end" pair to
-        ensure "end" is called at least once, and then, for each subrequest
+        set the callback and ensure "end" is called at least once, and then,
-        you start, call "begin" and for each subrequest you finish, call
+        for each subrequest you start, call "begin" and for each subrequest
-        "end".
+        you finish, call "end".
    METHODS FOR CONSUMERS
     These methods should only be used by the consuming side, i.e. the code
     awaits the condition.
            AnyEvent::Impl::Tk        based on Tk, very bad choice.
            AnyEvent::Impl::Qt        based on Qt, cannot be autoprobed (see its docs).
            AnyEvent::Impl::EventLib  based on Event::Lib, leaks memory and worse.
            AnyEvent::Impl::POE       based on POE, not generic enough for full support.
+           # warning, support for IO::Async is only partial, as it is too broken
+           # and limited toe ven support the AnyEvent API. See AnyEvent::Impl::Async.
+           AnyEvent::Impl::IOAsync   based on IO::Async, cannot be autoprobed (see its docs).
         There is no support for WxWidgets, as 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. Likewise, other POE backends can be used by AnyEvent by
     "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.
+        finds any problems, it will croak.
         In other words, enables "strict" mode.
-        Unlike "use strict", it is definitely recommended ot keep it off in
+        Unlike "use strict", 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_MODEL"
         This can be used to specify the event model to be used by AnyEvent,
             EV/Any   100000   224   2.88   0.34    0.27 EV + AnyEvent watchers
         CoroEV/Any   100000   224   2.85   0.35    0.28 coroutines + Coro::Signal
           Perl/Any   100000   452   4.13   0.73    0.95 pure perl implementation
        Event/Event    16000   517  32.20  31.80    0.81 Event native interface
          Event/Any    16000   590  35.85  31.55    1.06 Event + AnyEvent watchers
+       IOAsync/Any    16000   989  38.10  32.77   11.13 via IO::Async::Loop::IO_Poll
+       IOAsync/Any    16000   990  37.59  29.50   10.61 via IO::Async::Loop::Epoll
           Glib/Any    16000  1357 102.33  12.31   51.00 quadratic behaviour
             Tk/Any     2000  1860  27.20  66.31   14.00 SEGV with >> 2000 watchers
          POE/Event     2000  6328 109.99 751.67   14.02 via POE::Loop::Event
         POE/Select     2000  6027  94.54 809.13  579.80 via POE::Loop::Select
     few of them active), of course, but this was not subject of this
     benchmark.
     The "Event" module has a relatively high setup and callback invocation
     cost, but overall scores in on the third place.
+    "IO::Async" performs admirably well, about on par with "Event", even
+    when using its pure perl backend.
     "Glib"'s memory usage is quite a bit higher, but it features a faster
     callback invocation and overall ends up in the same class as "Event".
     However, Glib scales extremely badly, doubling the number of watchers
     increases the processing time by more than a factor of four, making it
     single "request", that is, reading the token from the pipe and
     forwarding it to another server. This includes deleting the old timeout
     and creating a new one that moves the timeout into the future.
    Results
-        name sockets create  request
+         name sockets create  request
-          EV   20000  69.01    11.16
+           EV   20000  69.01    11.16
-        Perl   20000  73.32    35.87
+         Perl   20000  73.32    35.87
+      IOAsync   20000 157.00    98.14 epoll
+      IOAsync   20000 159.31   616.06 poll
-       Event   20000 212.62   257.32
+        Event   20000 212.62   257.32
-        Glib   20000 651.16  1896.30
+         Glib   20000 651.16  1896.30
-         POE   20000 349.67 12317.24 uses POE::Loop::Event
+          POE   20000 349.67 12317.24 uses POE::Loop::Event
    Discussion
     This benchmark *does* measure scalability and overall performance of the
     particular event loop.
     EV is again fastest. Since it is using epoll on my system, the setup
     time is relatively high, though.
     Perl surprisingly comes second. It is much faster than the C-based event
     loops Event and Glib.
+    IO::Async performs very well when using its epoll backend, and still
+    quite good compared to Glib when using its pure perl backend.
     Event suffers from high setup time as well (look at its code and you
     will understand why). Callback invocation also has a high overhead
     compared to the "$_->() for .."-style loop that the Perl event loop
     uses. Event uses select or poll in basically all documented
   THE IO::Lambda BENCHMARK
     Recently I was told about the benchmark in the IO::Lambda manpage, which
     could be misinterpreted to make AnyEvent look bad. In fact, the
     benchmark simply compares IO::Lambda with POE, and IO::Lambda looks
     better (which shouldn't come as a surprise to anybody). As such, the
-    benchmark is fine, and shows that the AnyEvent backend from IO::Lambda
+    benchmark is fine, and mostly shows that the AnyEvent backend from
-    isn't very optimal. But how would AnyEvent compare when used without the
+    IO::Lambda isn't very optimal. But how would AnyEvent compare when used
-    extra baggage? To explore this, I wrote the equivalent benchmark for
+    without the extra baggage? To explore this, I wrote the equivalent
-    AnyEvent.
+    benchmark for AnyEvent.
     The benchmark itself creates an echo-server, and then, for 500 times,
     connects to the echo server, sends a line, waits for the reply, and then
     creates the next connection. This is a rather bad benchmark, as it
-    doesn't test the efficiency of the framework, but it is a benchmark
+    doesn't test the efficiency of the framework or much non-blocking I/O,
-    nevertheless.
+    but it is a benchmark nevertheless.
        name                    runtime
        Lambda/select           0.330 sec
           + optimized          0.122 sec
        Lambda/AnyEvent         0.327 sec
        AnyEvent/select/nb      0.085 sec
        AnyEvent/EV/nb          0.068 sec
           +state machine       0.134 sec
-    The benchmark is also a bit unfair (my fault) - the IO::Lambda
+    The benchmark is also a bit unfair (my fault): the IO::Lambda/POE
     benchmarks actually make blocking connects and use 100% blocking I/O,
     defeating the purpose of an event-based solution. All of the newly
     written AnyEvent benchmarks use 100% non-blocking connects (using
     AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS
-    resolver), so AnyEvent is at a disadvantage here as non-blocking
+    resolver), so AnyEvent is at a disadvantage here, as non-blocking
     connects generally require a lot more bookkeeping and event handling
     than blocking connects (which involve a single syscall only).
     The last AnyEvent benchmark additionally uses AnyEvent::Handle, which
-    offers similar expressive power as POE and IO::Lambda (using
+    offers similar expressive power as POE and IO::Lambda, using
-    conventional Perl syntax), which means both the echo server and the
+    conventional Perl syntax. This means that both the echo server and the
-    client are 100% non-blocking w.r.t. I/O, further placing it at a
+    client are 100% non-blocking, further placing it at a disadvantage.
-    disadvantage.
-    As you can see, AnyEvent + EV even beats the hand-optimised "raw sockets
+    As you can see, the AnyEvent + EV combination even beats the
-    benchmark", while AnyEvent + its pure perl backend easily beats
+    hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
-    IO::Lambda and POE.
+    backend easily beats IO::Lambda and POE.
     And even the 100% non-blocking version written using the high-level (and
-    slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda, even
+    slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda by a
-    thought it does all of DNS, tcp-connect and socket I/O in a non-blocking
+    large margin, even though it does all of DNS, tcp-connect and socket I/O
-    way.
+    in a non-blocking way.
-    The two AnyEvent benchmarks can be found as eg/ae0.pl and eg/ae2.pl in
+    The two AnyEvent benchmarks programs can be found as eg/ae0.pl and
-    the AnyEvent distribution, the remaining benchmarks are part of the
+    eg/ae2.pl in the AnyEvent distribution, the remaining benchmarks are
-    IO::lambda distribution and were used without any changes.
+    part of the IO::lambda distribution and were used without any changes.
 SIGNALS
     AnyEvent currently installs handlers for these signals:
     SIGCHLD
         A handler for "SIGCHLD" is installed by AnyEvent's child watcher
         emulation for event loops that do not support them natively. Also,
         some event loops install a similar handler.
+        If, when AnyEvent is loaded, SIGCHLD is set to IGNORE, then AnyEvent
+        will reset it to default, to avoid losing child exit statuses.
     SIGPIPE
         A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
         "undef" when AnyEvent gets loaded.
     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

Diff Legend

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

Comparing AnyEvent/README (file contents): Revision 1.40 by root, Tue Jun 23 23:37:32 2009 UTC vs. Revision 1.42 by root, Mon Jun 29 21:00:32 2009 UTC

Diff Legend

Comparing AnyEvent/README (file contents):
Revision 1.40 by root, Tue Jun 23 23:37:32 2009 UTC vs.
Revision 1.42 by root, Mon Jun 29 21:00:32 2009 UTC