[ViewVC] Diff of: cvs/AnyEvent/lib/AnyEvent.pm

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.406 by root, Thu Nov 15 01:17:29 2012 UTC vs.
Revision 1.418 by root, Tue Jan 21 16:48:34 2014 UTC

 Example 2: fire an event after 0.5 seconds, then roughly every second.
    my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
       warn "timeout\n";
-   };
+   });
 =head3 TIMING ISSUES
 There are two ways to handle timers: based on real time (relative, "fire
 in 10 seconds") and based on wallclock time (absolute, "fire at 12
 Example: fork a process and wait for it
    my $done = AnyEvent->condvar;
+   # this forks and immediately calls exit in the child. this
+   # normally has all sorts of bad consequences for your parent,
+   # so take this as an example only. always fork and exec,
+   # or call POSIX::_exit, in real code.
    my $pid = fork or exit 5;
    my $w = AnyEvent->child (
       pid => $pid,
       cb  => sub {
 This works because for every event source (EOF on file handle), there is
 one call to C<begin>, so the condvar waits for all calls to C<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
+there are results to be passed back, and the number of tasks that are
 begun can potentially be zero:
    my $cv = AnyEvent->condvar;
    my %result;
       };
    }
    $cv->end;
+   ...
+   my $results = $cv->recv;
 This code fragment supposedly pings a number of hosts and calls
 C<send> after results for all then have have been gathered - in any
 order. To achieve this, the code issues a call to C<begin> when it starts
 each ping request and calls C<end> when it has received some result for
 it. Since C<begin> and C<end> only maintain a counter, the order in which
 In list context, all parameters passed to C<send> will be returned,
 in scalar context only the first one will be returned.
 Note that doing a blocking wait in a callback is not supported by any
-event loop, that is, recursive invocation of a blocking C<< ->recv
+event loop, that is, recursive invocation of a blocking C<< ->recv >> is
->> is not allowed, and the C<recv> call will C<croak> if such a
+not allowed and the C<recv> call will C<croak> if such a condition is
-condition is detected. This condition can be slightly loosened by using
+detected. This requirement can be dropped by relying on L<Coro::AnyEvent>
-L<Coro::AnyEvent>, which allows you to do a blocking C<< ->recv >> from
+, which allows you to do a blocking C<< ->recv >> from any thread
-any thread that doesn't run the event loop itself.
+that doesn't run the event loop itself. L<Coro::AnyEvent> is loaded
+automatically when L<Coro> is used with L<AnyEvent>, so code does not need
+to do anything special to take advantage of that: any code that would
+normally block your program because it calls C<recv>, be executed in an
+C<async> thread instead without blocking other threads.
 Not all event models support a blocking wait - some die in that case
 (programs might want to do that to stay interactive), so I<if you are
 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
 To understand the usefulness of this function, consider a function that
 asynchronously does something for you and returns some transaction
 object or guard to let you cancel the operation. For example,
 C<AnyEvent::Socket::tcp_connect>:
-   # start a conenction attempt unless one is active
+   # start a connection attempt unless one is active
    $self->{connect_guard} ||= AnyEvent::Socket::tcp_connect "www.example.net", 80, sub {
       delete $self->{connect_guard};
       ...
    };
 a longer non-exhaustive list), and the list is heavily biased towards
 modules of the AnyEvent author himself :)
 =over 4
-=item L<AnyEvent::Util>
+=item L<AnyEvent::Util> (part of the AnyEvent distribution)
 Contains various utility functions that replace often-used blocking
 functions such as C<inet_aton> with event/callback-based versions.
-=item L<AnyEvent::Socket>
+=item L<AnyEvent::Socket> (part of the AnyEvent distribution)
 Provides various utility functions for (internet protocol) sockets,
 addresses and name resolution. Also functions to create non-blocking tcp
 connections or tcp servers, with IPv6 and SRV record support and more.
-=item L<AnyEvent::Handle>
+=item L<AnyEvent::Handle> (part of the AnyEvent distribution)
 Provide read and write buffers, manages watchers for reads and writes,
 supports raw and formatted I/O, I/O queued and fully transparent and
 non-blocking SSL/TLS (via L<AnyEvent::TLS>).
-=item L<AnyEvent::DNS>
+=item L<AnyEvent::DNS> (part of the AnyEvent distribution)
 Provides rich asynchronous DNS resolver capabilities.
 =item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP>
 Implement event-based interfaces to the protocols of the same name (for
 the curious, IGS is the International Go Server and FCP is the Freenet
 Client Protocol).
-=item L<AnyEvent::AIO>
+=item L<AnyEvent::AIO> (part of the AnyEvent distribution)
 Truly asynchronous (as opposed to non-blocking) I/O, should be in the
 toolbox of every event programmer. AnyEvent::AIO transparently fuses
 L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based
 file I/O, and much more.
+=item L<AnyEvent::Fork>, L<AnyEvent::Fork::RPC>, L<AnyEvent::Fork::Pool>, L<AnyEvent::Fork::Remote>
+These let you safely fork new subprocesses, either locally or
+remotely (e.g.v ia ssh), using some RPC protocol or not, without
+the limitations normally imposed by fork (AnyEvent works fine for
+example). Dynamically-resized worker pools are obviously included as well.
+And they are quite tiny and fast as well - "abusing" L<AnyEvent::Fork>
+just to exec external programs can easily beat using C<fork> and C<exec>
+(or even C<system>) in most programs.
 =item L<AnyEvent::Filesys::Notify>
 AnyEvent is good for non-blocking stuff, but it can't detect file or
 path changes (e.g. "watch this directory for new files", "watch this
 do just that in a portbale fashion, supporting inotify on GNU/Linux and
 some weird, without doubt broken, stuff on OS X to monitor files. It can
 fall back to blocking scans at regular intervals transparently on other
 platforms, so it's about as portable as it gets.
-(I haven't used it myself, but I haven't heard anybody complaining about
+(I haven't used it myself, but it seems the biggest problem with it is
-it yet).
+it quite bad performance).
 =item L<AnyEvent::DBI>
 Executes L<DBI> requests asynchronously in a proxy process for you,
 notifying you in an event-based way when the operation is finished.
-=item L<AnyEvent::HTTPD>
-A simple embedded webserver.
 =item L<AnyEvent::FastPing>
 The fastest ping in the west.
 =cut
 package AnyEvent;
-# basically a tuned-down version of common::sense
+BEGIN {
-sub common_sense {
+   require "AnyEvent/constants.pl";
-   # from common:.sense 3.5
+   &AnyEvent::common_sense;
-   local $^W;
-   ${^WARNING_BITS} ^= ${^WARNING_BITS} ^ "\x3c\x3f\x33\x00\x0f\xf0\x0f\xc0\xf0\xfc\x33\x00";
-   # use strict vars subs - NO UTF-8, as Util.pm doesn't like this atm. (uts46data.pl)
-   $^H |= 0x00000600;
 }
-BEGIN { AnyEvent::common_sense }
 use Carp ();
-our $VERSION = '7.03';
+our $VERSION = '7.07';
 our $MODEL;
 our @ISA;
 our @REGISTRY;
 our $VERBOSE;
 our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
 our $MAX_SIGNAL_LATENCY = $ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY} || 10; # executes after the BEGIN block below (tainting!)
 BEGIN {
-   require "AnyEvent/constants.pl";
    eval "sub TAINT (){" . (${^TAINT}*1) . "}";
    delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
       if ${^TAINT};
 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 conenction and other failures anyways.
+small, as the program has to handle connection and other failures anyways.
 Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
 but support both and try to use both.  C<PERL_ANYEVENT_PROTOCOLS=ipv4>
 - only support IPv4, never try to resolve or contact IPv6
 addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
 This module is part of perl since release 5.008. It will be used when the
 chosen event library does not come with a timing source of its own. The
 pure-perl event loop (L<AnyEvent::Loop>) will additionally load it to
 try to use a monotonic clock for timing stability.
+=item L<AnyEvent::AIO> (and L<IO::AIO>)
+The default implementation of L<AnyEvent::IO> is to do I/O synchronously,
+stopping programs while they access the disk, which is fine for a lot of
+programs.
+Installing AnyEvent::AIO (and its IO::AIO dependency) makes it switch to
+a true asynchronous implementation, so event processing can continue even
+while waiting for disk I/O.
 =back
 =head1 FORK
 usually happens when the first AnyEvent watcher is created, or the library
 is loaded).
 If you have to fork, you must either do so I<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.
+something completely out of the scope of AnyEvent (see below).
 The problem of doing event processing in the parent I<and> the child
 is much more complicated: even for backends that I<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 C<exec>
+parent and child, which is almost never what you want. Using C<exec>
-to start worker children from some kind of manage rprocess is usually
+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
+L<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 L<AnyEvent::Fork> module (and some related modules
+such as L<AnyEvent::Fork::RPC>, L<AnyEvent::Fork::Pool> and
+L<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 L<AnyEvent::Fork> safely and without
+any special precautions.
 =head1 SECURITY CONSIDERATIONS
 AnyEvent can be forced to load any event model via

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.406 by root, Thu Nov 15 01:17:29 2012 UTC vs. Revision 1.418 by root, Tue Jan 21 16:48:34 2014 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.406 by root, Thu Nov 15 01:17:29 2012 UTC vs.
Revision 1.418 by root, Tue Jan 21 16:48:34 2014 UTC