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.170 by root, Wed Jul 9 11:53:40 2008 UTC vs.
Revision 1.180 by root, Sat Sep 6 07:00:45 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
… …
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
385>> method, usually without arguments. The only argument pair allowed is 394>> method, usually without arguments. The only argument pair allowed is
395
386C<cb>, which specifies a callback to be called when the condition variable 396C<cb>, which specifies a callback to be called when the condition variable
387becomes true. 397becomes true, with the condition variable as the first argument (but not
398the results).
388 399
389After creation, the condition variable is "false" until it becomes "true" 400After creation, the condition variable is "false" until it becomes "true"
390by calling the C<send> method (or calling the condition variable as if it 401by 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<< 402were a callback, read about the caveats in the description for the C<<
392->send >> method). 403->send >> method).
… …
448 459
449 my $done = AnyEvent->condvar; 460 my $done = AnyEvent->condvar;
450 my $delay = AnyEvent->timer (after => 5, cb => $done); 461 my $delay = AnyEvent->timer (after => 5, cb => $done);
451 $done->recv; 462 $done->recv;
452 463
464Example: Imagine an API that returns a condvar and doesn't support
465callbacks. This is how you make a synchronous call, for example from
466the main program:
467
468 use AnyEvent::CouchDB;
469
470 ...
471
472 my @info = $couchdb->info->recv;
473
474And this is how you would just ste a callback to be called whenever the
475results are available:
476
477 $couchdb->info->cb (sub {
478 my @info = $_[0]->recv;
479 });
480
453=head3 METHODS FOR PRODUCERS 481=head3 METHODS FOR PRODUCERS
454 482
455These methods should only be used by the producing side, i.e. the 483These methods should only be used by the producing side, i.e. the
456code/module that eventually sends the signal. Note that it is also 484code/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 485the producer side which creates the condvar in most cases, but it isn't
… …
590=item $bool = $cv->ready 618=item $bool = $cv->ready
591 619
592Returns true when the condition is "true", i.e. whether C<send> or 620Returns true when the condition is "true", i.e. whether C<send> or
593C<croak> have been called. 621C<croak> have been called.
594 622
595=item $cb = $cv->cb ([new callback]) 623=item $cb = $cv->cb ($cb->($cv))
596 624
597This is a mutator function that returns the callback set and optionally 625This is a mutator function that returns the callback set and optionally
598replaces it before doing so. 626replaces it before doing so.
599 627
600The callback will be called when the condition becomes "true", i.e. when 628The callback will be called when the condition becomes "true", i.e. when
… …
822=cut 850=cut
823 851
824package AnyEvent; 852package AnyEvent;
825 853
826no warnings; 854no warnings;
827use strict; 855use strict qw(vars subs);
828 856
829use Carp; 857use Carp;
830 858
831our $VERSION = 4.2; 859our $VERSION = 4.233;
832our $MODEL; 860our $MODEL;
833 861
834our $AUTOLOAD; 862our $AUTOLOAD;
835our @ISA; 863our @ISA;
836 864
… …
988 1016
989package AnyEvent::Base; 1017package AnyEvent::Base;
990 1018
991# default implementation for now and time 1019# default implementation for now and time
992 1020
993use Time::HiRes (); 1021BEGIN {
1022 if (eval "use Time::HiRes (); time (); 1") {
1023 *_time = \&Time::HiRes::time;
1024 # if (eval "use POSIX (); (POSIX::times())...
1025 } else {
1026 *_time = \&CORE::time; # epic fail
1027 }
1028}
994 1029
995sub time { Time::HiRes::time } 1030sub time { _time }
996sub now { Time::HiRes::time } 1031sub now { _time }
997 1032
998# default implementation for ->condvar 1033# default implementation for ->condvar
999 1034
1000sub condvar { 1035sub condvar {
1001 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar:: 1036 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
… …
1140 1175
1141# undocumented/compatibility with pre-3.4 1176# undocumented/compatibility with pre-3.4
1142*broadcast = \&send; 1177*broadcast = \&send;
1143*wait = \&_wait; 1178*wait = \&_wait;
1144 1179
1180=head1 ERROR AND EXCEPTION HANDLING
1181
1182In general, AnyEvent does not do any error handling - it relies on the
1183caller to do that if required. The L<AnyEvent::Strict> module (see also
1184the C<PERL_ANYEVENT_STRICT> environment variable, below) provides strict
1185checking of all AnyEvent methods, however, which is highly useful during
1186development.
1187
1188As for exception handling (i.e. runtime errors and exceptions thrown while
1189executing a callback), this is not only highly event-loop specific, but
1190also not in any way wrapped by this module, as this is the job of the main
1191program.
1192
1193The pure perl event loop simply re-throws the exception (usually
1194within C<< condvar->recv >>), the L<Event> and L<EV> modules call C<<
1195$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1196so on.
1197
1198=head1 ENVIRONMENT VARIABLES
1199
1200The following environment variables are used by this module or its
1201submodules:
1202
1203=over 4
1204
1205=item C<PERL_ANYEVENT_VERBOSE>
1206
1207By default, AnyEvent will be completely silent except in fatal
1208conditions. You can set this environment variable to make AnyEvent more
1209talkative.
1210
1211When set to C<1> or higher, causes AnyEvent to warn about unexpected
1212conditions, such as not being able to load the event model specified by
1213C<PERL_ANYEVENT_MODEL>.
1214
1215When set to C<2> or higher, cause AnyEvent to report to STDERR which event
1216model it chooses.
1217
1218=item C<PERL_ANYEVENT_STRICT>
1219
1220AnyEvent does not do much argument checking by default, as thorough
1221argument checking is very costly. Setting this variable to a true value
1222will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1223check the arguments passed to most method calls. If it finds any problems
1224it will croak.
1225
1226In other words, enables "strict" mode.
1227
1228Unlike C<use strict>, it is definitely recommended ot keep it off in
1229production. Keeping C<PERL_ANYEVENT_STRICT=1> in your environment while
1230developing programs can be very useful, however.
1231
1232=item C<PERL_ANYEVENT_MODEL>
1233
1234This can be used to specify the event model to be used by AnyEvent, before
1235auto detection and -probing kicks in. It must be a string consisting
1236entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
1237and the resulting module name is loaded and if the load was successful,
1238used as event model. If it fails to load AnyEvent will proceed with
1239auto detection and -probing.
1240
1241This functionality might change in future versions.
1242
1243For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1244could start your program like this:
1245
1246 PERL_ANYEVENT_MODEL=Perl perl ...
1247
1248=item C<PERL_ANYEVENT_PROTOCOLS>
1249
1250Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1251for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1252of auto probing).
1253
1254Must be set to a comma-separated list of protocols or address families,
1255current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1256used, and preference will be given to protocols mentioned earlier in the
1257list.
1258
1259This variable can effectively be used for denial-of-service attacks
1260against local programs (e.g. when setuid), although the impact is likely
1261small, as the program has to handle connection errors already-
1262
1263Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1264but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1265- only support IPv4, never try to resolve or contact IPv6
1266addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1267IPv6, but prefer IPv6 over IPv4.
1268
1269=item C<PERL_ANYEVENT_EDNS0>
1270
1271Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
1272for DNS. This extension is generally useful to reduce DNS traffic, but
1273some (broken) firewalls drop such DNS packets, which is why it is off by
1274default.
1275
1276Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1277EDNS0 in its DNS requests.
1278
1279=item C<PERL_ANYEVENT_MAX_FORKS>
1280
1281The maximum number of child processes that C<AnyEvent::Util::fork_call>
1282will create in parallel.
1283
1284=back
1285
1145=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1286=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1146 1287
1147This is an advanced topic that you do not normally need to use AnyEvent in 1288This is an advanced topic that you do not normally need to use AnyEvent in
1148a module. This section is only of use to event loop authors who want to 1289a module. This section is only of use to event loop authors who want to
1149provide AnyEvent compatibility. 1290provide AnyEvent compatibility.
… …
1182 1323
1183I<rxvt-unicode> also cheats a bit by not providing blocking access to 1324I<rxvt-unicode> also cheats a bit by not providing blocking access to
1184condition variables: code blocking while waiting for a condition will 1325condition variables: code blocking while waiting for a condition will
1185C<die>. This still works with most modules/usages, and blocking calls must 1326C<die>. This still works with most modules/usages, and blocking calls must
1186not be done in an interactive application, so it makes sense. 1327not be done in an interactive application, so it makes sense.
1187
1188=head1 ENVIRONMENT VARIABLES
1189
1190The following environment variables are used by this module:
1191
1192=over 4
1193
1194=item C<PERL_ANYEVENT_VERBOSE>
1195
1196By default, AnyEvent will be completely silent except in fatal
1197conditions. You can set this environment variable to make AnyEvent more
1198talkative.
1199
1200When set to C<1> or higher, causes AnyEvent to warn about unexpected
1201conditions, such as not being able to load the event model specified by
1202C<PERL_ANYEVENT_MODEL>.
1203
1204When set to C<2> or higher, cause AnyEvent to report to STDERR which event
1205model it chooses.
1206
1207=item C<PERL_ANYEVENT_STRICT>
1208
1209AnyEvent does not do much argument checking by default, as thorough
1210argument checking is very costly. Setting this variable to a true value
1211will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1212check the arguments passed to most method calls. If it finds any problems
1213it will croak.
1214
1215In other words, enables "strict" mode.
1216
1217Unlike C<use strict> it is definitely recommended ot keep it off in
1218production.
1219
1220=item C<PERL_ANYEVENT_MODEL>
1221
1222This can be used to specify the event model to be used by AnyEvent, before
1223auto detection and -probing kicks in. It must be a string consisting
1224entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
1225and the resulting module name is loaded and if the load was successful,
1226used as event model. If it fails to load AnyEvent will proceed with
1227auto detection and -probing.
1228
1229This functionality might change in future versions.
1230
1231For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1232could start your program like this:
1233
1234 PERL_ANYEVENT_MODEL=Perl perl ...
1235
1236=item C<PERL_ANYEVENT_PROTOCOLS>
1237
1238Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1239for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1240of auto probing).
1241
1242Must be set to a comma-separated list of protocols or address families,
1243current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1244used, and preference will be given to protocols mentioned earlier in the
1245list.
1246
1247This variable can effectively be used for denial-of-service attacks
1248against local programs (e.g. when setuid), although the impact is likely
1249small, as the program has to handle connection errors already-
1250
1251Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1252but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1253- only support IPv4, never try to resolve or contact IPv6
1254addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1255IPv6, but prefer IPv6 over IPv4.
1256
1257=item C<PERL_ANYEVENT_EDNS0>
1258
1259Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
1260for DNS. This extension is generally useful to reduce DNS traffic, but
1261some (broken) firewalls drop such DNS packets, which is why it is off by
1262default.
1263
1264Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1265EDNS0 in its DNS requests.
1266
1267=item C<PERL_ANYEVENT_MAX_FORKS>
1268
1269The maximum number of child processes that C<AnyEvent::Util::fork_call>
1270will create in parallel.
1271
1272=back
1273 1328
1274=head1 EXAMPLE PROGRAM 1329=head1 EXAMPLE PROGRAM
1275 1330
1276The following program uses an I/O watcher to read data from STDIN, a timer 1331The following program uses an I/O watcher to read data from STDIN, a timer
1277to display a message once per second, and a condition variable to quit the 1332to display a message once per second, and a condition variable to quit the

Diff Legend

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