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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.221 by root, Fri Jun 26 06:33:17 2009 UTC vs.
Revision 1.229 by root, Wed Jul 8 02:01:12 2009 UTC

 =head2 I/O WATCHERS
 You can create an I/O watcher by calling the C<< AnyEvent->io >> method
 with the following mandatory key-value pairs as arguments:
-C<fh> is the Perl I<file handle> (I<not> file descriptor) to watch
+C<fh> is the Perl I<file handle> (or a naked file descriptor) to watch
 for events (AnyEvent might or might not keep a reference to this file
 handle). Note that only file handles pointing to things for which
 non-blocking operation makes sense are allowed. This includes sockets,
 most character devices, pipes, fifos and so on, but not for example files
 or block devices.
 =item $cv->begin ([group callback])
 =item $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 C<< ->begin >> will increment a counter, and every call to
 C<< ->end >> will decrement it.  If the counter reaches C<0> in C<< ->end
 >>, the (last) callback passed to C<begin> will be executed. That callback
 is I<supposed> to call C<< ->send >>, but that is not required. If no
 callback was set, C<send> will be called without any arguments.
-Let's clarify this with the ping example:
+You can think of C<< $cv->send >> giving you an OR condition (one call
+sends), while C<< $cv->begin >> and C<< $cv->end >> giving you an AND
+condition (all C<begin> calls must be C<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 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
+begung can potentially be zero:
    my $cv = AnyEvent->condvar;
    my %result;
    $cv->begin (sub { $cv->send (\%result) });
 loop, which serves two important purposes: first, it sets the callback
 to be called once the counter reaches C<0>, and second, it ensures that
 C<send> is called even when C<no> hosts are being pinged (the loop
 doesn't execute once).
-This is the general pattern when you "fan out" into multiple subrequests:
+This is the general pattern when you "fan out" into multiple (but
-use an outer C<begin>/C<end> pair to set the callback and ensure C<end>
+potentially none) subrequests: use an outer C<begin>/C<end> pair to set
-is called at least once, and then, for each subrequest you start, call
+the callback and ensure C<end> is called at least once, and then, for each
-C<begin> and for each subrequest you finish, call C<end>.
+subrequest you start, call C<begin> and for each subrequest you finish,
+call C<end>.
 =back
 =head3 METHODS FOR CONSUMERS
 no warnings;
 use strict qw(vars subs);
 use Carp;
-our $VERSION = 4.42;
+our $VERSION = 4.8;
 our $MODEL;
 our $AUTOLOAD;
 our @ISA;
 # allow only one watcher per fd, so we dup it to get a different one).
 sub _dupfh($$;$$) {
    my ($poll, $fh, $r, $w) = @_;
    # cygwin requires the fh mode to be matching, unix doesn't
-   my ($rw, $mode) = $poll eq "r" ? ($r, "<")
+   my ($rw, $mode) = $poll eq "r" ? ($r, "<") : ($w, ">");
-                   : $poll eq "w" ? ($w, ">")
-                   : Carp::croak "AnyEvent->io requires poll set to either 'r' or 'w'";
-   open my $fh2, "$mode&" . fileno $fh
+   open my $fh2, "$mode&", $fh
-      or die "cannot dup() filehandle: $!,";
+      or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,";
    # we assume CLOEXEC is already set by perl in all important cases
    ($fh2, $rw)
 }
 =item C<PERL_ANYEVENT_MAX_FORKS>
 The maximum number of child processes that C<AnyEvent::Util::fork_call>
 will create in parallel.
+=item C<PERL_ANYEVENT_MAX_OUTSTANDING_DNS>
+The default value for the C<max_outstanding> parameter for the default DNS
+resolver - this is the maximum number of parallel DNS requests that are
+sent to the DNS server.
+=item C<PERL_ANYEVENT_RESOLV_CONF>
+The file to use instead of F</etc/resolv.conf> (or OS-specific
+configuration) in the default resolver. When set to the empty string, no
+default config will be used.
+=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
+When neither C<ca_file> nor C<ca_path> was specified during
+L<AnyEvent::TLS> context creation, and either of these environment
+variables exist, they will be used to specify CA certificate locations
+instead of a system-dependent default.
 =back
 =head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.221 by root, Fri Jun 26 06:33:17 2009 UTC vs. Revision 1.229 by root, Wed Jul 8 02:01:12 2009 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.221 by root, Fri Jun 26 06:33:17 2009 UTC vs.
Revision 1.229 by root, Wed Jul 8 02:01:12 2009 UTC