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

Comparing AnyEvent/README (file contents):
Revision 1.28 by root, Sat Jul 12 20:45:27 2008 UTC vs.
Revision 1.42 by root, Mon Jun 29 21:00:32 2009 UTC

1NAME 1NAME
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - provide framework for multiple event loops
3 3
4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event 4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported
5 loops 5 event loops.
6 6
7SYNOPSIS 7SYNOPSIS
8 use AnyEvent; 8 use AnyEvent;
9 9
10 # file descriptor readable
10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { 11 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
12
13 # one-shot or repeating timers
14 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
15 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
16
17 print AnyEvent->now; # prints current event loop time
18 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
19
20 # POSIX signal
21 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
22
23 # child process exit
24 my $w = AnyEvent->child (pid => $pid, cb => sub {
25 my ($pid, $status) = @_;
11 ... 26 ...
12 }); 27 });
13 28
14 my $w = AnyEvent->timer (after => $seconds, cb => sub { 29 # called when event loop idle (if applicable)
15 ... 30 my $w = AnyEvent->idle (cb => sub { ... });
16 });
17 31
18 my $w = AnyEvent->condvar; # stores whether a condition was flagged 32 my $w = AnyEvent->condvar; # stores whether a condition was flagged
19 $w->send; # wake up current and all future recv's 33 $w->send; # wake up current and all future recv's
20 $w->recv; # enters "main loop" till $condvar gets ->send 34 $w->recv; # enters "main loop" till $condvar gets ->send
35 # use a condvar in callback mode:
36 $w->cb (sub { $_[0]->recv });
21 37
22INTRODUCTION/TUTORIAL 38INTRODUCTION/TUTORIAL
23 This manpage is mainly a reference manual. If you are interested in a 39 This manpage is mainly a reference manual. If you are interested in a
24 tutorial or some gentle introduction, have a look at the AnyEvent::Intro 40 tutorial or some gentle introduction, have a look at the AnyEvent::Intro
25 manpage. 41 manpage.
… …
123 These watchers are normal Perl objects with normal Perl lifetime. After 139 These watchers are normal Perl objects with normal Perl lifetime. After
124 creating a watcher it will immediately "watch" for events and invoke the 140 creating a watcher it will immediately "watch" for events and invoke the
125 callback when the event occurs (of course, only when the event model is 141 callback when the event occurs (of course, only when the event model is
126 in control). 142 in control).
127 143
144 Note that callbacks must not permanently change global variables
145 potentially in use by the event loop (such as $_ or $[) and that
146 callbacks must not "die". The former is good programming practise in
147 Perl and the latter stems from the fact that exception handling differs
148 widely between event loops.
149
128 To disable the watcher you have to destroy it (e.g. by setting the 150 To disable the watcher you have to destroy it (e.g. by setting the
129 variable you store it in to "undef" or otherwise deleting all references 151 variable you store it in to "undef" or otherwise deleting all references
130 to it). 152 to it).
131 153
132 All watchers are created by calling a method on the "AnyEvent" class. 154 All watchers are created by calling a method on the "AnyEvent" class.
… …
147 169
148 I/O WATCHERS 170 I/O WATCHERS
149 You can create an I/O watcher by calling the "AnyEvent->io" method with 171 You can create an I/O watcher by calling the "AnyEvent->io" method with
150 the following mandatory key-value pairs as arguments: 172 the following mandatory key-value pairs as arguments:
151 173
152 "fh" the Perl *file handle* (*not* file descriptor) to watch for events 174 "fh" is the Perl *file handle* (*not* file descriptor) to watch for
153 (AnyEvent might or might not keep a reference to this file handle). 175 events (AnyEvent might or might not keep a reference to this file
176 handle). Note that only file handles pointing to things for which
177 non-blocking operation makes sense are allowed. This includes sockets,
178 most character devices, pipes, fifos and so on, but not for example
179 files or block devices.
180
154 "poll" must be a string that is either "r" or "w", which creates a 181 "poll" must be a string that is either "r" or "w", which creates a
155 watcher waiting for "r"eadable or "w"ritable events, respectively. "cb" 182 watcher waiting for "r"eadable or "w"ritable events, respectively.
183
156 is the callback to invoke each time the file handle becomes ready. 184 "cb" is the callback to invoke each time the file handle becomes ready.
157 185
158 Although the callback might get passed parameters, their value and 186 Although the callback might get passed parameters, their value and
159 presence is undefined and you cannot rely on them. Portable AnyEvent 187 presence is undefined and you cannot rely on them. Portable AnyEvent
160 callbacks cannot use arguments passed to I/O watcher callbacks. 188 callbacks cannot use arguments passed to I/O watcher callbacks.
161 189
… …
293 In either case, if you care (and in most cases, you don't), then you 321 In either case, if you care (and in most cases, you don't), then you
294 can get whatever behaviour you want with any event loop, by taking 322 can get whatever behaviour you want with any event loop, by taking
295 the difference between "AnyEvent->time" and "AnyEvent->now" into 323 the difference between "AnyEvent->time" and "AnyEvent->now" into
296 account. 324 account.
297 325
326 AnyEvent->now_update
327 Some event loops (such as EV or AnyEvent::Impl::Perl) cache the
328 current time for each loop iteration (see the discussion of
329 AnyEvent->now, above).
330
331 When a callback runs for a long time (or when the process sleeps),
332 then this "current" time will differ substantially from the real
333 time, which might affect timers and time-outs.
334
335 When this is the case, you can call this method, which will update
336 the event loop's idea of "current time".
337
338 Note that updating the time *might* cause some events to be handled.
339
298 SIGNAL WATCHERS 340 SIGNAL WATCHERS
299 You can watch for signals using a signal watcher, "signal" is the signal 341 You can watch for signals using a signal watcher, "signal" is the signal
300 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl 342 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl
301 callback to be invoked whenever a signal occurs. 343 callback to be invoked whenever a signal occurs.
302 344
… …
321 363
322 CHILD PROCESS WATCHERS 364 CHILD PROCESS WATCHERS
323 You can also watch on a child process exit and catch its exit status. 365 You can also watch on a child process exit and catch its exit status.
324 366
325 The child process is specified by the "pid" argument (if set to 0, it 367 The child process is specified by the "pid" argument (if set to 0, it
326 watches for any child process exit). The watcher will trigger as often 368 watches for any child process exit). The watcher will triggered only
327 as status change for the child are received. This works by installing a 369 when the child process has finished and an exit status is available, not
328 signal handler for "SIGCHLD". The callback will be called with the pid 370 on any trace events (stopped/continued).
329 and exit status (as returned by waitpid), so unlike other watcher types, 371
330 you *can* rely on child watcher callback arguments. 372 The callback will be called with the pid and exit status (as returned by
373 waitpid), so unlike other watcher types, you *can* rely on child watcher
374 callback arguments.
375
376 This watcher type works by installing a signal handler for "SIGCHLD",
377 and since it cannot be shared, nothing else should use SIGCHLD or reap
378 random child processes (waiting for specific child processes, e.g.
379 inside "system", is just fine).
331 380
332 There is a slight catch to child watchers, however: you usually start 381 There is a slight catch to child watchers, however: you usually start
333 them *after* the child process was created, and this means the process 382 them *after* the child process was created, and this means the process
334 could have exited already (and no SIGCHLD will be sent anymore). 383 could have exited already (and no SIGCHLD will be sent anymore).
335 384
336 Not all event models handle this correctly (POE doesn't), but even for 385 Not all event models handle this correctly (neither POE nor IO::Async
386 do, see their AnyEvent::Impl manpages for details), but even for event
337 event models that *do* handle this correctly, they usually need to be 387 models that *do* handle this correctly, they usually need to be loaded
338 loaded before the process exits (i.e. before you fork in the first 388 before the process exits (i.e. before you fork in the first place).
339 place). 389 AnyEvent's pure perl event loop handles all cases correctly regardless
390 of when you start the watcher.
340 391
341 This means you cannot create a child watcher as the very first thing in 392 This means you cannot create a child watcher as the very first thing in
342 an AnyEvent program, you *have* to create at least one watcher before 393 an AnyEvent program, you *have* to create at least one watcher before
343 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 394 you "fork" the child (alternatively, you can call "AnyEvent::detect").
344 395
345 Example: fork a process and wait for it 396 Example: fork a process and wait for it
346 397
347 my $done = AnyEvent->condvar; 398 my $done = AnyEvent->condvar;
348 399
349 my $pid = fork or exit 5; 400 my $pid = fork or exit 5;
350 401
351 my $w = AnyEvent->child ( 402 my $w = AnyEvent->child (
352 pid => $pid, 403 pid => $pid,
353 cb => sub { 404 cb => sub {
354 my ($pid, $status) = @_; 405 my ($pid, $status) = @_;
355 warn "pid $pid exited with status $status"; 406 warn "pid $pid exited with status $status";
356 $done->send; 407 $done->send;
357 }, 408 },
358 ); 409 );
359 410
360 # do something else, then wait for process exit 411 # do something else, then wait for process exit
361 $done->recv; 412 $done->recv;
413
414 IDLE WATCHERS
415 Sometimes there is a need to do something, but it is not so important to
416 do it instantly, but only when there is nothing better to do. This
417 "nothing better to do" is usually defined to be "no other events need
418 attention by the event loop".
419
420 Idle watchers ideally get invoked when the event loop has nothing better
421 to do, just before it would block the process to wait for new events.
422 Instead of blocking, the idle watcher is invoked.
423
424 Most event loops unfortunately do not really support idle watchers (only
425 EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent
426 will simply call the callback "from time to time".
427
428 Example: read lines from STDIN, but only process them when the program
429 is otherwise idle:
430
431 my @lines; # read data
432 my $idle_w;
433 my $io_w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
434 push @lines, scalar <STDIN>;
435
436 # start an idle watcher, if not already done
437 $idle_w ||= AnyEvent->idle (cb => sub {
438 # handle only one line, when there are lines left
439 if (my $line = shift @lines) {
440 print "handled when idle: $line";
441 } else {
442 # otherwise disable the idle watcher again
443 undef $idle_w;
444 }
445 });
446 });
362 447
363 CONDITION VARIABLES 448 CONDITION VARIABLES
364 If you are familiar with some event loops you will know that all of them 449 If you are familiar with some event loops you will know that all of them
365 require you to run some blocking "loop", "run" or similar function that 450 require you to run some blocking "loop", "run" or similar function that
366 will actively watch for new events and call your callbacks. 451 will actively watch for new events and call your callbacks.
… …
371 The instrument to do that is called a "condition variable", so called 456 The instrument to do that is called a "condition variable", so called
372 because they represent a condition that must become true. 457 because they represent a condition that must become true.
373 458
374 Condition variables can be created by calling the "AnyEvent->condvar" 459 Condition variables can be created by calling the "AnyEvent->condvar"
375 method, usually without arguments. The only argument pair allowed is 460 method, usually without arguments. The only argument pair allowed is
461
376 "cb", which specifies a callback to be called when the condition 462 "cb", which specifies a callback to be called when the condition
377 variable becomes true. 463 variable becomes true, with the condition variable as the first argument
464 (but not the results).
378 465
379 After creation, the condition variable is "false" until it becomes 466 After creation, the condition variable is "false" until it becomes
380 "true" by calling the "send" method (or calling the condition variable 467 "true" by calling the "send" method (or calling the condition variable
381 as if it were a callback, read about the caveats in the description for 468 as if it were a callback, read about the caveats in the description for
382 the "->send" method). 469 the "->send" method).
… …
438 525
439 my $done = AnyEvent->condvar; 526 my $done = AnyEvent->condvar;
440 my $delay = AnyEvent->timer (after => 5, cb => $done); 527 my $delay = AnyEvent->timer (after => 5, cb => $done);
441 $done->recv; 528 $done->recv;
442 529
530 Example: Imagine an API that returns a condvar and doesn't support
531 callbacks. This is how you make a synchronous call, for example from the
532 main program:
533
534 use AnyEvent::CouchDB;
535
536 ...
537
538 my @info = $couchdb->info->recv;
539
540 And this is how you would just ste a callback to be called whenever the
541 results are available:
542
543 $couchdb->info->cb (sub {
544 my @info = $_[0]->recv;
545 });
546
443 METHODS FOR PRODUCERS 547 METHODS FOR PRODUCERS
444 These methods should only be used by the producing side, i.e. the 548 These methods should only be used by the producing side, i.e. the
445 code/module that eventually sends the signal. Note that it is also the 549 code/module that eventually sends the signal. Note that it is also the
446 producer side which creates the condvar in most cases, but it isn't 550 producer side which creates the condvar in most cases, but it isn't
447 uncommon for the consumer to create it as well. 551 uncommon for the consumer to create it as well.
… …
473 This can be used to signal any errors to the condition variable 577 This can be used to signal any errors to the condition variable
474 user/consumer. 578 user/consumer.
475 579
476 $cv->begin ([group callback]) 580 $cv->begin ([group callback])
477 $cv->end 581 $cv->end
478 These two methods are EXPERIMENTAL and MIGHT CHANGE.
479
480 These two methods can be used to combine many transactions/events 582 These two methods can be used to combine many transactions/events
481 into one. For example, a function that pings many hosts in parallel 583 into one. For example, a function that pings many hosts in parallel
482 might want to use a condition variable for the whole process. 584 might want to use a condition variable for the whole process.
483 585
484 Every call to "->begin" will increment a counter, and every call to 586 Every call to "->begin" will increment a counter, and every call to
485 "->end" will decrement it. If the counter reaches 0 in "->end", the 587 "->end" will decrement it. If the counter reaches 0 in "->end", the
486 (last) callback passed to "begin" will be executed. That callback is 588 (last) callback passed to "begin" will be executed. That callback is
487 *supposed* to call "->send", but that is not required. If no 589 *supposed* to call "->send", but that is not required. If no
488 callback was set, "send" will be called without any arguments. 590 callback was set, "send" will be called without any arguments.
489 591
490 Let's clarify this with the ping example: 592 You can think of "$cv->send" giving you an OR condition (one call
593 sends), while "$cv->begin" and "$cv->end" giving you an AND
594 condition (all "begin" calls must be "end"'ed before the condvar
595 sends).
596
597 Let's start with a simple example: you have two I/O watchers (for
598 example, STDOUT and STDERR for a program), and you want to wait for
599 both streams to close before activating a condvar:
600
601 my $cv = AnyEvent->condvar;
602
603 $cv->begin; # first watcher
604 my $w1 = AnyEvent->io (fh => $fh1, cb => sub {
605 defined sysread $fh1, my $buf, 4096
606 or $cv->end;
607 });
608
609 $cv->begin; # second watcher
610 my $w2 = AnyEvent->io (fh => $fh2, cb => sub {
611 defined sysread $fh2, my $buf, 4096
612 or $cv->end;
613 });
614
615 $cv->recv;
616
617 This works because for every event source (EOF on file handle),
618 there is one call to "begin", so the condvar waits for all calls to
619 "end" before sending.
620
621 The ping example mentioned above is slightly more complicated, as
622 the there are results to be passwd back, and the number of tasks
623 that are begung can potentially be zero:
491 624
492 my $cv = AnyEvent->condvar; 625 my $cv = AnyEvent->condvar;
493 626
494 my %result; 627 my %result;
495 $cv->begin (sub { $cv->send (\%result) }); 628 $cv->begin (sub { $cv->send (\%result) });
… …
515 the loop, which serves two important purposes: first, it sets the 648 the loop, which serves two important purposes: first, it sets the
516 callback to be called once the counter reaches 0, and second, it 649 callback to be called once the counter reaches 0, and second, it
517 ensures that "send" is called even when "no" hosts are being pinged 650 ensures that "send" is called even when "no" hosts are being pinged
518 (the loop doesn't execute once). 651 (the loop doesn't execute once).
519 652
520 This is the general pattern when you "fan out" into multiple 653 This is the general pattern when you "fan out" into multiple (but
521 subrequests: use an outer "begin"/"end" pair to set the callback and 654 potentially none) subrequests: use an outer "begin"/"end" pair to
522 ensure "end" is called at least once, and then, for each subrequest 655 set the callback and ensure "end" is called at least once, and then,
523 you start, call "begin" and for each subrequest you finish, call 656 for each subrequest you start, call "begin" and for each subrequest
524 "end". 657 you finish, call "end".
525 658
526 METHODS FOR CONSUMERS 659 METHODS FOR CONSUMERS
527 These methods should only be used by the consuming side, i.e. the code 660 These methods should only be used by the consuming side, i.e. the code
528 awaits the condition. 661 awaits the condition.
529 662
… …
567 700
568 $bool = $cv->ready 701 $bool = $cv->ready
569 Returns true when the condition is "true", i.e. whether "send" or 702 Returns true when the condition is "true", i.e. whether "send" or
570 "croak" have been called. 703 "croak" have been called.
571 704
572 $cb = $cv->cb ([new callback]) 705 $cb = $cv->cb ($cb->($cv))
573 This is a mutator function that returns the callback set and 706 This is a mutator function that returns the callback set and
574 optionally replaces it before doing so. 707 optionally replaces it before doing so.
575 708
576 The callback will be called when the condition becomes "true", i.e. 709 The callback will be called when the condition becomes "true", i.e.
577 when "send" or "croak" are called, with the only argument being the 710 when "send" or "croak" are called, with the only argument being the
… …
595 AnyEvent::Impl::Tk based on Tk, very bad choice. 728 AnyEvent::Impl::Tk based on Tk, very bad choice.
596 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs). 729 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
597 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 730 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
598 AnyEvent::Impl::POE based on POE, not generic enough for full support. 731 AnyEvent::Impl::POE based on POE, not generic enough for full support.
599 732
733 # warning, support for IO::Async is only partial, as it is too broken
734 # and limited toe ven support the AnyEvent API. See AnyEvent::Impl::Async.
735 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed (see its docs).
736
600 There is no support for WxWidgets, as WxWidgets has no support for 737 There is no support for WxWidgets, as WxWidgets has no support for
601 watching file handles. However, you can use WxWidgets through the 738 watching file handles. However, you can use WxWidgets through the
602 POE Adaptor, as POE has a Wx backend that simply polls 20 times per 739 POE Adaptor, as POE has a Wx backend that simply polls 20 times per
603 second, which was considered to be too horrible to even consider for 740 second, which was considered to be too horrible to even consider for
604 AnyEvent. Likewise, other POE backends can be used by AnyEvent by 741 AnyEvent. Likewise, other POE backends can be used by AnyEvent by
… …
742 879
743 AnyEvent::IGS 880 AnyEvent::IGS
744 A non-blocking interface to the Internet Go Server protocol (used by 881 A non-blocking interface to the Internet Go Server protocol (used by
745 App::IGS). 882 App::IGS).
746 883
884 AnyEvent::IRC
885 AnyEvent based IRC client module family (replacing the older
747 Net::IRC3 886 Net::IRC3).
748 AnyEvent based IRC client module family.
749 887
750 Net::XMPP2 888 Net::XMPP2
751 AnyEvent based XMPP (Jabber protocol) module family. 889 AnyEvent based XMPP (Jabber protocol) module family.
752 890
753 Net::FCP 891 Net::FCP
… …
762 900
763 IO::Lambda 901 IO::Lambda
764 The lambda approach to I/O - don't ask, look there. Can use 902 The lambda approach to I/O - don't ask, look there. Can use
765 AnyEvent. 903 AnyEvent.
766 904
767SUPPLYING YOUR OWN EVENT MODEL INTERFACE 905ERROR AND EXCEPTION HANDLING
768 This is an advanced topic that you do not normally need to use AnyEvent 906 In general, AnyEvent does not do any error handling - it relies on the
769 in a module. This section is only of use to event loop authors who want 907 caller to do that if required. The AnyEvent::Strict module (see also the
770 to provide AnyEvent compatibility. 908 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
909 checking of all AnyEvent methods, however, which is highly useful during
910 development.
771 911
772 If you need to support another event library which isn't directly 912 As for exception handling (i.e. runtime errors and exceptions thrown
773 supported by AnyEvent, you can supply your own interface to it by 913 while executing a callback), this is not only highly event-loop
774 pushing, before the first watcher gets created, the package name of the 914 specific, but also not in any way wrapped by this module, as this is the
775 event module and the package name of the interface to use onto 915 job of the main program.
776 @AnyEvent::REGISTRY. You can do that before and even without loading
777 AnyEvent, so it is reasonably cheap.
778 916
779 Example: 917 The pure perl event loop simply re-throws the exception (usually within
780 918 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
781 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 919 Glib uses "install_exception_handler" and so on.
782
783 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
784 package/class when it finds the "urxvt" package/module is already
785 loaded.
786
787 When AnyEvent is loaded and asked to find a suitable event model, it
788 will first check for the presence of urxvt by trying to "use" the
789 "urxvt::anyevent" module.
790
791 The class should provide implementations for all watcher types. See
792 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
793 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
794 the sources.
795
796 If you don't provide "signal" and "child" watchers than AnyEvent will
797 provide suitable (hopefully) replacements.
798
799 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
800 terminal emulator uses the above line as-is. An interface isn't included
801 in AnyEvent because it doesn't make sense outside the embedded
802 interpreter inside *rxvt-unicode*, and it is updated and maintained as
803 part of the *rxvt-unicode* distribution.
804
805 *rxvt-unicode* also cheats a bit by not providing blocking access to
806 condition variables: code blocking while waiting for a condition will
807 "die". This still works with most modules/usages, and blocking calls
808 must not be done in an interactive application, so it makes sense.
809 920
810ENVIRONMENT VARIABLES 921ENVIRONMENT VARIABLES
811 The following environment variables are used by this module: 922 The following environment variables are used by this module or its
923 submodules.
924
925 Note that AnyEvent will remove *all* environment variables starting with
926 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
927 enabled.
812 928
813 "PERL_ANYEVENT_VERBOSE" 929 "PERL_ANYEVENT_VERBOSE"
814 By default, AnyEvent will be completely silent except in fatal 930 By default, AnyEvent will be completely silent except in fatal
815 conditions. You can set this environment variable to make AnyEvent 931 conditions. You can set this environment variable to make AnyEvent
816 more talkative. 932 more talkative.
… …
825 "PERL_ANYEVENT_STRICT" 941 "PERL_ANYEVENT_STRICT"
826 AnyEvent does not do much argument checking by default, as thorough 942 AnyEvent does not do much argument checking by default, as thorough
827 argument checking is very costly. Setting this variable to a true 943 argument checking is very costly. Setting this variable to a true
828 value will cause AnyEvent to load "AnyEvent::Strict" and then to 944 value will cause AnyEvent to load "AnyEvent::Strict" and then to
829 thoroughly check the arguments passed to most method calls. If it 945 thoroughly check the arguments passed to most method calls. If it
830 finds any problems it will croak. 946 finds any problems, it will croak.
831 947
832 In other words, enables "strict" mode. 948 In other words, enables "strict" mode.
833 949
834 Unlike "use strict" it is definitely recommended ot keep it off in 950 Unlike "use strict", it is definitely recommended to keep it off in
835 production. 951 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment
952 while developing programs can be very useful, however.
836 953
837 "PERL_ANYEVENT_MODEL" 954 "PERL_ANYEVENT_MODEL"
838 This can be used to specify the event model to be used by AnyEvent, 955 This can be used to specify the event model to be used by AnyEvent,
839 before auto detection and -probing kicks in. It must be a string 956 before auto detection and -probing kicks in. It must be a string
840 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 957 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
859 mentioned will be used, and preference will be given to protocols 976 mentioned will be used, and preference will be given to protocols
860 mentioned earlier in the list. 977 mentioned earlier in the list.
861 978
862 This variable can effectively be used for denial-of-service attacks 979 This variable can effectively be used for denial-of-service attacks
863 against local programs (e.g. when setuid), although the impact is 980 against local programs (e.g. when setuid), although the impact is
864 likely small, as the program has to handle connection errors 981 likely small, as the program has to handle conenction and other
865 already- 982 failures anyways.
866 983
867 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over 984 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
868 IPv6, but support both and try to use both. 985 IPv6, but support both and try to use both.
869 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to 986 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
870 resolve or contact IPv6 addresses. 987 resolve or contact IPv6 addresses.
… …
881 EDNS0 in its DNS requests. 998 EDNS0 in its DNS requests.
882 999
883 "PERL_ANYEVENT_MAX_FORKS" 1000 "PERL_ANYEVENT_MAX_FORKS"
884 The maximum number of child processes that 1001 The maximum number of child processes that
885 "AnyEvent::Util::fork_call" will create in parallel. 1002 "AnyEvent::Util::fork_call" will create in parallel.
1003
1004SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1005 This is an advanced topic that you do not normally need to use AnyEvent
1006 in a module. This section is only of use to event loop authors who want
1007 to provide AnyEvent compatibility.
1008
1009 If you need to support another event library which isn't directly
1010 supported by AnyEvent, you can supply your own interface to it by
1011 pushing, before the first watcher gets created, the package name of the
1012 event module and the package name of the interface to use onto
1013 @AnyEvent::REGISTRY. You can do that before and even without loading
1014 AnyEvent, so it is reasonably cheap.
1015
1016 Example:
1017
1018 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
1019
1020 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
1021 package/class when it finds the "urxvt" package/module is already
1022 loaded.
1023
1024 When AnyEvent is loaded and asked to find a suitable event model, it
1025 will first check for the presence of urxvt by trying to "use" the
1026 "urxvt::anyevent" module.
1027
1028 The class should provide implementations for all watcher types. See
1029 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
1030 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
1031 the sources.
1032
1033 If you don't provide "signal" and "child" watchers than AnyEvent will
1034 provide suitable (hopefully) replacements.
1035
1036 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
1037 terminal emulator uses the above line as-is. An interface isn't included
1038 in AnyEvent because it doesn't make sense outside the embedded
1039 interpreter inside *rxvt-unicode*, and it is updated and maintained as
1040 part of the *rxvt-unicode* distribution.
1041
1042 *rxvt-unicode* also cheats a bit by not providing blocking access to
1043 condition variables: code blocking while waiting for a condition will
1044 "die". This still works with most modules/usages, and blocking calls
1045 must not be done in an interactive application, so it makes sense.
886 1046
887EXAMPLE PROGRAM 1047EXAMPLE PROGRAM
888 The following program uses an I/O watcher to read data from STDIN, a 1048 The following program uses an I/O watcher to read data from STDIN, a
889 timer to display a message once per second, and a condition variable to 1049 timer to display a message once per second, and a condition variable to
890 quit the program when the user enters quit: 1050 quit the program when the user enters quit:
… …
1077 *destroy* is the time, in microseconds, that it takes to destroy a 1237 *destroy* is the time, in microseconds, that it takes to destroy a
1078 single watcher. 1238 single watcher.
1079 1239
1080 Results 1240 Results
1081 name watchers bytes create invoke destroy comment 1241 name watchers bytes create invoke destroy comment
1082 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1242 EV/EV 400000 224 0.47 0.35 0.27 EV native interface
1083 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers 1243 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
1084 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal 1244 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
1085 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation 1245 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
1086 Event/Event 16000 516 31.88 31.30 0.85 Event native interface 1246 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
1087 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers 1247 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
1248 IOAsync/Any 16000 989 38.10 32.77 11.13 via IO::Async::Loop::IO_Poll
1249 IOAsync/Any 16000 990 37.59 29.50 10.61 via IO::Async::Loop::Epoll
1088 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour 1250 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
1089 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers 1251 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
1090 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event 1252 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
1091 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select 1253 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
1092 1254
1093 Discussion 1255 Discussion
1094 The benchmark does *not* measure scalability of the event loop very 1256 The benchmark does *not* measure scalability of the event loop very
1095 well. For example, a select-based event loop (such as the pure perl one) 1257 well. For example, a select-based event loop (such as the pure perl one)
1096 can never compete with an event loop that uses epoll when the number of 1258 can never compete with an event loop that uses epoll when the number of
… …
1121 few of them active), of course, but this was not subject of this 1283 few of them active), of course, but this was not subject of this
1122 benchmark. 1284 benchmark.
1123 1285
1124 The "Event" module has a relatively high setup and callback invocation 1286 The "Event" module has a relatively high setup and callback invocation
1125 cost, but overall scores in on the third place. 1287 cost, but overall scores in on the third place.
1288
1289 "IO::Async" performs admirably well, about on par with "Event", even
1290 when using its pure perl backend.
1126 1291
1127 "Glib"'s memory usage is quite a bit higher, but it features a faster 1292 "Glib"'s memory usage is quite a bit higher, but it features a faster
1128 callback invocation and overall ends up in the same class as "Event". 1293 callback invocation and overall ends up in the same class as "Event".
1129 However, Glib scales extremely badly, doubling the number of watchers 1294 However, Glib scales extremely badly, doubling the number of watchers
1130 increases the processing time by more than a factor of four, making it 1295 increases the processing time by more than a factor of four, making it
… …
1201 single "request", that is, reading the token from the pipe and 1366 single "request", that is, reading the token from the pipe and
1202 forwarding it to another server. This includes deleting the old timeout 1367 forwarding it to another server. This includes deleting the old timeout
1203 and creating a new one that moves the timeout into the future. 1368 and creating a new one that moves the timeout into the future.
1204 1369
1205 Results 1370 Results
1206 name sockets create request 1371 name sockets create request
1207 EV 20000 69.01 11.16 1372 EV 20000 69.01 11.16
1208 Perl 20000 73.32 35.87 1373 Perl 20000 73.32 35.87
1374 IOAsync 20000 157.00 98.14 epoll
1375 IOAsync 20000 159.31 616.06 poll
1209 Event 20000 212.62 257.32 1376 Event 20000 212.62 257.32
1210 Glib 20000 651.16 1896.30 1377 Glib 20000 651.16 1896.30
1211 POE 20000 349.67 12317.24 uses POE::Loop::Event 1378 POE 20000 349.67 12317.24 uses POE::Loop::Event
1212 1379
1213 Discussion 1380 Discussion
1214 This benchmark *does* measure scalability and overall performance of the 1381 This benchmark *does* measure scalability and overall performance of the
1215 particular event loop. 1382 particular event loop.
1216 1383
1217 EV is again fastest. Since it is using epoll on my system, the setup 1384 EV is again fastest. Since it is using epoll on my system, the setup
1218 time is relatively high, though. 1385 time is relatively high, though.
1219 1386
1220 Perl surprisingly comes second. It is much faster than the C-based event 1387 Perl surprisingly comes second. It is much faster than the C-based event
1221 loops Event and Glib. 1388 loops Event and Glib.
1389
1390 IO::Async performs very well when using its epoll backend, and still
1391 quite good compared to Glib when using its pure perl backend.
1222 1392
1223 Event suffers from high setup time as well (look at its code and you 1393 Event suffers from high setup time as well (look at its code and you
1224 will understand why). Callback invocation also has a high overhead 1394 will understand why). Callback invocation also has a high overhead
1225 compared to the "$_->() for .."-style loop that the Perl event loop 1395 compared to the "$_->() for .."-style loop that the Perl event loop
1226 uses. Event uses select or poll in basically all documented 1396 uses. Event uses select or poll in basically all documented
… …
1277 1447
1278 Summary 1448 Summary
1279 * C-based event loops perform very well with small number of watchers, 1449 * C-based event loops perform very well with small number of watchers,
1280 as the management overhead dominates. 1450 as the management overhead dominates.
1281 1451
1452 THE IO::Lambda BENCHMARK
1453 Recently I was told about the benchmark in the IO::Lambda manpage, which
1454 could be misinterpreted to make AnyEvent look bad. In fact, the
1455 benchmark simply compares IO::Lambda with POE, and IO::Lambda looks
1456 better (which shouldn't come as a surprise to anybody). As such, the
1457 benchmark is fine, and mostly shows that the AnyEvent backend from
1458 IO::Lambda isn't very optimal. But how would AnyEvent compare when used
1459 without the extra baggage? To explore this, I wrote the equivalent
1460 benchmark for AnyEvent.
1461
1462 The benchmark itself creates an echo-server, and then, for 500 times,
1463 connects to the echo server, sends a line, waits for the reply, and then
1464 creates the next connection. This is a rather bad benchmark, as it
1465 doesn't test the efficiency of the framework or much non-blocking I/O,
1466 but it is a benchmark nevertheless.
1467
1468 name runtime
1469 Lambda/select 0.330 sec
1470 + optimized 0.122 sec
1471 Lambda/AnyEvent 0.327 sec
1472 + optimized 0.138 sec
1473 Raw sockets/select 0.077 sec
1474 POE/select, components 0.662 sec
1475 POE/select, raw sockets 0.226 sec
1476 POE/select, optimized 0.404 sec
1477
1478 AnyEvent/select/nb 0.085 sec
1479 AnyEvent/EV/nb 0.068 sec
1480 +state machine 0.134 sec
1481
1482 The benchmark is also a bit unfair (my fault): the IO::Lambda/POE
1483 benchmarks actually make blocking connects and use 100% blocking I/O,
1484 defeating the purpose of an event-based solution. All of the newly
1485 written AnyEvent benchmarks use 100% non-blocking connects (using
1486 AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS
1487 resolver), so AnyEvent is at a disadvantage here, as non-blocking
1488 connects generally require a lot more bookkeeping and event handling
1489 than blocking connects (which involve a single syscall only).
1490
1491 The last AnyEvent benchmark additionally uses AnyEvent::Handle, which
1492 offers similar expressive power as POE and IO::Lambda, using
1493 conventional Perl syntax. This means that both the echo server and the
1494 client are 100% non-blocking, further placing it at a disadvantage.
1495
1496 As you can see, the AnyEvent + EV combination even beats the
1497 hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
1498 backend easily beats IO::Lambda and POE.
1499
1500 And even the 100% non-blocking version written using the high-level (and
1501 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda by a
1502 large margin, even though it does all of DNS, tcp-connect and socket I/O
1503 in a non-blocking way.
1504
1505 The two AnyEvent benchmarks programs can be found as eg/ae0.pl and
1506 eg/ae2.pl in the AnyEvent distribution, the remaining benchmarks are
1507 part of the IO::lambda distribution and were used without any changes.
1508
1509SIGNALS
1510 AnyEvent currently installs handlers for these signals:
1511
1512 SIGCHLD
1513 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1514 emulation for event loops that do not support them natively. Also,
1515 some event loops install a similar handler.
1516
1517 If, when AnyEvent is loaded, SIGCHLD is set to IGNORE, then AnyEvent
1518 will reset it to default, to avoid losing child exit statuses.
1519
1520 SIGPIPE
1521 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1522 "undef" when AnyEvent gets loaded.
1523
1524 The rationale for this is that AnyEvent users usually do not really
1525 depend on SIGPIPE delivery (which is purely an optimisation for
1526 shell use, or badly-written programs), but "SIGPIPE" can cause
1527 spurious and rare program exits as a lot of people do not expect
1528 "SIGPIPE" when writing to some random socket.
1529
1530 The rationale for installing a no-op handler as opposed to ignoring
1531 it is that this way, the handler will be restored to defaults on
1532 exec.
1533
1534 Feel free to install your own handler, or reset it to defaults.
1535
1282FORK 1536FORK
1283 Most event libraries are not fork-safe. The ones who are usually are 1537 Most event libraries are not fork-safe. The ones who are usually are
1284 because they rely on inefficient but fork-safe "select" or "poll" calls. 1538 because they rely on inefficient but fork-safe "select" or "poll" calls.
1285 Only EV is fully fork-aware. 1539 Only EV is fully fork-aware.
1286 1540
… …
1297 1551
1298 You can make AnyEvent completely ignore this variable by deleting it 1552 You can make AnyEvent completely ignore this variable by deleting it
1299 before the first watcher gets created, e.g. with a "BEGIN" block: 1553 before the first watcher gets created, e.g. with a "BEGIN" block:
1300 1554
1301 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1555 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1302 1556
1303 use AnyEvent; 1557 use AnyEvent;
1304 1558
1305 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1559 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1306 be used to probe what backend is used and gain other information (which 1560 be used to probe what backend is used and gain other information (which
1307 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL), 1561 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
1308 and $ENV{PERL_ANYEGENT_STRICT}. 1562 and $ENV{PERL_ANYEVENT_STRICT}.
1563
1564 Note that AnyEvent will remove *all* environment variables starting with
1565 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
1566 enabled.
1309 1567
1310BUGS 1568BUGS
1311 Perl 5.8 has numerous memleaks that sometimes hit this module and are 1569 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1312 hard to work around. If you suffer from memleaks, first upgrade to Perl 1570 hard to work around. If you suffer from memleaks, first upgrade to Perl
1313 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other 1571 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
1314 annoying mamleaks, such as leaking on "map" and "grep" but it is usually 1572 annoying memleaks, such as leaking on "map" and "grep" but it is usually
1315 not as pronounced). 1573 not as pronounced).
1316 1574
1317SEE ALSO 1575SEE ALSO
1318 Utility functions: AnyEvent::Util. 1576 Utility functions: AnyEvent::Util.
1319 1577

Diff Legend

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