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.168 by root, Tue Jul 8 23:53:37 2008 UTC vs.
Revision 1.173 by root, Mon Jul 21 03:47:22 2008 UTC

… …
6 6
7=head1 SYNOPSIS 7=head1 SYNOPSIS
8 8
9 use AnyEvent; 9 use AnyEvent;
10 10
11 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { 11 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { ... });
12 ...
13 });
14 12
15 my $w = AnyEvent->timer (after => $seconds, cb => sub { 13 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
14 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
15
16 print AnyEvent->now; # prints current event loop time
17 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
18
19 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
20
21 my $w = AnyEvent->child (pid => $pid, cb => sub {
22 my ($pid, $status) = @_;
16 ... 23 ...
17 }); 24 });
18 25
19 my $w = AnyEvent->condvar; # stores whether a condition was flagged 26 my $w = AnyEvent->condvar; # stores whether a condition was flagged
20 $w->send; # wake up current and all future recv's 27 $w->send; # wake up current and all future recv's
21 $w->recv; # enters "main loop" till $condvar gets ->send 28 $w->recv; # enters "main loop" till $condvar gets ->send
29 # use a condvar in callback mode:
30 $w->cb (sub { $_[0]->recv });
22 31
23=head1 INTRODUCTION/TUTORIAL 32=head1 INTRODUCTION/TUTORIAL
24 33
25This manpage is mainly a reference manual. If you are interested 34This manpage is mainly a reference manual. If you are interested
26in a tutorial or some gentle introduction, have a look at the 35in a tutorial or some gentle introduction, have a look at the
… …
380 389
381The instrument to do that is called a "condition variable", so called 390The instrument to do that is called a "condition variable", so called
382because they represent a condition that must become true. 391because they represent a condition that must become true.
383 392
384Condition variables can be created by calling the C<< AnyEvent->condvar 393Condition variables can be created by calling the C<< AnyEvent->condvar
394
385>> method, usually without arguments. The only argument pair allowed is 395>> method, usually without arguments. The only argument pair allowed is
396
386C<cb>, which specifies a callback to be called when the condition variable 397C<cb>, which specifies a callback to be called when the condition variable
387becomes true. 398becomes true, with the condition variable as the first argument (but not
399the results).
388 400
389After creation, the condition variable is "false" until it becomes "true" 401After creation, the condition variable is "false" until it becomes "true"
390by calling the C<send> method (or calling the condition variable as if it 402by calling the C<send> method (or calling the condition variable as if it
391were a callback, read about the caveats in the description for the C<< 403were a callback, read about the caveats in the description for the C<<
392->send >> method). 404->send >> method).
… …
448 460
449 my $done = AnyEvent->condvar; 461 my $done = AnyEvent->condvar;
450 my $delay = AnyEvent->timer (after => 5, cb => $done); 462 my $delay = AnyEvent->timer (after => 5, cb => $done);
451 $done->recv; 463 $done->recv;
452 464
465Example: Imagine an API that returns a condvar and doesn't support
466callbacks. This is how you make a synchronous call, for example from
467the main program:
468
469 use AnyEvent::CouchDB;
470
471 ...
472
473 my @info = $couchdb->info->recv;
474
475And this is how you would just ste a callback to be called whenever the
476results are available:
477
478 $couchdb->info->cb (sub {
479 my @info = $_[0]->recv;
480 });
481
453=head3 METHODS FOR PRODUCERS 482=head3 METHODS FOR PRODUCERS
454 483
455These methods should only be used by the producing side, i.e. the 484These methods should only be used by the producing side, i.e. the
456code/module that eventually sends the signal. Note that it is also 485code/module that eventually sends the signal. Note that it is also
457the producer side which creates the condvar in most cases, but it isn't 486the producer side which creates the condvar in most cases, but it isn't
… …
590=item $bool = $cv->ready 619=item $bool = $cv->ready
591 620
592Returns true when the condition is "true", i.e. whether C<send> or 621Returns true when the condition is "true", i.e. whether C<send> or
593C<croak> have been called. 622C<croak> have been called.
594 623
595=item $cb = $cv->cb ([new callback]) 624=item $cb = $cv->cb ($cb->($cv))
596 625
597This is a mutator function that returns the callback set and optionally 626This is a mutator function that returns the callback set and optionally
598replaces it before doing so. 627replaces it before doing so.
599 628
600The callback will be called when the condition becomes "true", i.e. when 629The callback will be called when the condition becomes "true", i.e. when
… …
826no warnings; 855no warnings;
827use strict; 856use strict;
828 857
829use Carp; 858use Carp;
830 859
831our $VERSION = 4.2; 860our $VERSION = 4.22;
832our $MODEL; 861our $MODEL;
833 862
834our $AUTOLOAD; 863our $AUTOLOAD;
835our @ISA; 864our @ISA;
836 865
… …
963 992
964 my $class = shift; 993 my $class = shift;
965 $class->$func (@_); 994 $class->$func (@_);
966} 995}
967 996
997# utility function to dup a filehandle. this is used by many backends
998# to support binding more than one watcher per filehandle (they usually
999# allow only one watcher per fd, so we dup it to get a different one).
1000sub _dupfh($$$$) {
1001 my ($poll, $fh, $r, $w) = @_;
1002
1003 require Fcntl;
1004
1005 # cygwin requires the fh mode to be matching, unix doesn't
1006 my ($rw, $mode) = $poll eq "r" ? ($r, "<")
1007 : $poll eq "w" ? ($w, ">")
1008 : Carp::croak "AnyEvent->io requires poll set to either 'r' or 'w'";
1009
1010 open my $fh2, "$mode&" . fileno $fh
1011 or die "cannot dup() filehandle: $!";
1012
1013 # we assume CLOEXEC is already set by perl in all important cases
1014
1015 ($fh2, $rw)
1016}
1017
968package AnyEvent::Base; 1018package AnyEvent::Base;
969 1019
970# default implementation for now and time 1020# default implementation for now and time
971 1021
972use Time::HiRes (); 1022use Time::HiRes ();
… …
1185 1235
1186=item C<PERL_ANYEVENT_STRICT> 1236=item C<PERL_ANYEVENT_STRICT>
1187 1237
1188AnyEvent does not do much argument checking by default, as thorough 1238AnyEvent does not do much argument checking by default, as thorough
1189argument checking is very costly. Setting this variable to a true value 1239argument checking is very costly. Setting this variable to a true value
1190will cause AnyEvent to thoroughly check the arguments passed to most 1240will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1191method calls and croaks if it finds any problems. In other words, enables 1241check the arguments passed to most method calls. If it finds any problems
1242it will croak.
1243
1244In other words, enables "strict" mode.
1245
1192"strict" mode. Unlike C<use strict> it is definitely recommended ot keep 1246Unlike C<use strict> it is definitely recommended ot keep it off in
1193it off in production. 1247production.
1194 1248
1195=item C<PERL_ANYEVENT_MODEL> 1249=item C<PERL_ANYEVENT_MODEL>
1196 1250
1197This can be used to specify the event model to be used by AnyEvent, before 1251This can be used to specify the event model to be used by AnyEvent, before
1198auto detection and -probing kicks in. It must be a string consisting 1252auto detection and -probing kicks in. It must be a string consisting

Diff Legend

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