ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent.pm
(Generate patch)

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

… …
176=head2 I/O WATCHERS 176=head2 I/O WATCHERS
177 177
178You can create an I/O watcher by calling the C<< AnyEvent->io >> method 178You can create an I/O watcher by calling the C<< AnyEvent->io >> method
179with the following mandatory key-value pairs as arguments: 179with the following mandatory key-value pairs as arguments:
180 180
181C<fh> is the Perl I<file handle> (I<not> file descriptor) to watch 181C<fh> is the Perl I<file handle> (I<not> file descriptor, see below) to
182for events (AnyEvent might or might not keep a reference to this file 182watch for events (AnyEvent might or might not keep a reference to this
183handle). Note that only file handles pointing to things for which 183file handle). Note that only file handles pointing to things for which
184non-blocking operation makes sense are allowed. This includes sockets, 184non-blocking operation makes sense are allowed. This includes sockets,
185most character devices, pipes, fifos and so on, but not for example files 185most character devices, pipes, fifos and so on, but not for example files
186or block devices. 186or block devices.
187 187
188C<poll> must be a string that is either C<r> or C<w>, which creates a 188C<poll> must be a string that is either C<r> or C<w>, which creates a
… …
208 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 208 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
209 chomp (my $input = <STDIN>); 209 chomp (my $input = <STDIN>);
210 warn "read: $input\n"; 210 warn "read: $input\n";
211 undef $w; 211 undef $w;
212 }); 212 });
213
214=head3 GETTING A FILE HANDLE FROM A FILE DESCRIPTOR
215
216It is not uncommon to only have a file descriptor, while AnyEvent requires
217a Perl file handle.
218
219There are basically two methods to convert a file descriptor into a file handle. If you own
220the file descriptor, you can open it with C<&=>, as in:
221
222 open my $fh, "<&=$fileno" or die "xxx: ยง!";
223
224This will "own" the file descriptor, meaning that when C<$fh> is
225destroyed, it will automatically close the C<$fileno>. Also, note that
226the open mode (read, write, read/write) must correspond with how the
227underlying file descriptor was opened.
228
229In many cases, taking over the file descriptor is now what you want, in
230which case the only alternative is to dup the file descriptor:
231
232 open my $fh, "<&$fileno" or die "xxx: $!";
233
234This has the advantage of not closing the file descriptor and the
235disadvantage of making a slow copy.
213 236
214=head2 TIME WATCHERS 237=head2 TIME WATCHERS
215 238
216You can create a time watcher by calling the C<< AnyEvent->timer >> 239You can create a time watcher by calling the C<< AnyEvent->timer >>
217method with the following mandatory arguments: 240method with the following mandatory arguments:
… …
599 622
600=item $cv->begin ([group callback]) 623=item $cv->begin ([group callback])
601 624
602=item $cv->end 625=item $cv->end
603 626
604These two methods are EXPERIMENTAL and MIGHT CHANGE.
605
606These two methods can be used to combine many transactions/events into 627These two methods can be used to combine many transactions/events into
607one. For example, a function that pings many hosts in parallel might want 628one. For example, a function that pings many hosts in parallel might want
608to use a condition variable for the whole process. 629to use a condition variable for the whole process.
609 630
610Every call to C<< ->begin >> will increment a counter, and every call to 631Every call to C<< ->begin >> will increment a counter, and every call to
611C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end 632C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end
612>>, the (last) callback passed to C<begin> will be executed. That callback 633>>, the (last) callback passed to C<begin> will be executed. That callback
613is I<supposed> to call C<< ->send >>, but that is not required. If no 634is I<supposed> to call C<< ->send >>, but that is not required. If no
614callback was set, C<send> will be called without any arguments. 635callback was set, C<send> will be called without any arguments.
615 636
616Let's clarify this with the ping example: 637You can think of C<< $cv->send >> giving you an OR condition (one call
638sends), while C<< $cv->begin >> and C<< $cv->end >> giving you an AND
639condition (all C<begin> calls must be C<end>'ed before the condvar sends).
640
641Let's start with a simple example: you have two I/O watchers (for example,
642STDOUT and STDERR for a program), and you want to wait for both streams to
643close before activating a condvar:
644
645 my $cv = AnyEvent->condvar;
646
647 $cv->begin; # first watcher
648 my $w1 = AnyEvent->io (fh => $fh1, cb => sub {
649 defined sysread $fh1, my $buf, 4096
650 or $cv->end;
651 });
652
653 $cv->begin; # second watcher
654 my $w2 = AnyEvent->io (fh => $fh2, cb => sub {
655 defined sysread $fh2, my $buf, 4096
656 or $cv->end;
657 });
658
659 $cv->recv;
660
661This works because for every event source (EOF on file handle), there is
662one call to C<begin>, so the condvar waits for all calls to C<end> before
663sending.
664
665The ping example mentioned above is slightly more complicated, as the
666there are results to be passwd back, and the number of tasks that are
667begung can potentially be zero:
617 668
618 my $cv = AnyEvent->condvar; 669 my $cv = AnyEvent->condvar;
619 670
620 my %result; 671 my %result;
621 $cv->begin (sub { $cv->send (\%result) }); 672 $cv->begin (sub { $cv->send (\%result) });
… …
641loop, which serves two important purposes: first, it sets the callback 692loop, which serves two important purposes: first, it sets the callback
642to be called once the counter reaches C<0>, and second, it ensures that 693to be called once the counter reaches C<0>, and second, it ensures that
643C<send> is called even when C<no> hosts are being pinged (the loop 694C<send> is called even when C<no> hosts are being pinged (the loop
644doesn't execute once). 695doesn't execute once).
645 696
646This is the general pattern when you "fan out" into multiple subrequests: 697This is the general pattern when you "fan out" into multiple (but
647use an outer C<begin>/C<end> pair to set the callback and ensure C<end> 698potentially none) subrequests: use an outer C<begin>/C<end> pair to set
648is called at least once, and then, for each subrequest you start, call 699the callback and ensure C<end> is called at least once, and then, for each
649C<begin> and for each subrequest you finish, call C<end>. 700subrequest you start, call C<begin> and for each subrequest you finish,
701call C<end>.
650 702
651=back 703=back
652 704
653=head3 METHODS FOR CONSUMERS 705=head3 METHODS FOR CONSUMERS
654 706
… …
939no warnings; 991no warnings;
940use strict qw(vars subs); 992use strict qw(vars subs);
941 993
942use Carp; 994use Carp;
943 995
944our $VERSION = 4.42; 996our $VERSION = 4.8;
945our $MODEL; 997our $MODEL;
946 998
947our $AUTOLOAD; 999our $AUTOLOAD;
948our @ISA; 1000our @ISA;
949 1001
… …
1442=item C<PERL_ANYEVENT_MAX_FORKS> 1494=item C<PERL_ANYEVENT_MAX_FORKS>
1443 1495
1444The maximum number of child processes that C<AnyEvent::Util::fork_call> 1496The maximum number of child processes that C<AnyEvent::Util::fork_call>
1445will create in parallel. 1497will create in parallel.
1446 1498
1499=item C<PERL_ANYEVENT_MAX_OUTSTANDING_DNS>
1500
1501The default value for the C<max_outstanding> parameter for the default DNS
1502resolver - this is the maximum number of parallel DNS requests that are
1503sent to the DNS server.
1504
1505=item C<PERL_ANYEVENT_RESOLV_CONF>
1506
1507The file to use instead of F</etc/resolv.conf> (or OS-specific
1508configuration) in the default resolver. When set to the empty string, no
1509default config will be used.
1510
1511=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
1512
1513When neither C<ca_file> nor C<ca_path> was specified during
1514L<AnyEvent::TLS> context creation, and either of these environment
1515variables exist, they will be used to specify CA certificate locations
1516instead of a system-dependent default.
1517
1447=back 1518=back
1448 1519
1449=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1520=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1450 1521
1451This is an advanced topic that you do not normally need to use AnyEvent in 1522This is an advanced topic that you do not normally need to use AnyEvent in

Diff Legend

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