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

Comparing AnyEvent/README (file contents):
Revision 1.40 by root, Tue Jun 23 23:37:32 2009 UTC vs.
Revision 1.47 by root, Mon Jul 20 22:39:57 2009 UTC

1NAME 1NAME
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - events independent of event loop implementation
3 3
4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported 4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported
5 event loops. 5 event loops.
6 6
7SYNOPSIS 7SYNOPSIS
… …
37 37
38INTRODUCTION/TUTORIAL 38INTRODUCTION/TUTORIAL
39 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
40 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
41 manpage. 41 manpage.
42
43SUPPORT
44 There is a mailinglist for discussing all things AnyEvent, and an IRC
45 channel, too.
46
47 See the AnyEvent project page at the Schmorpforge Ta-Sa Software
48 Respository, at <http://anyevent.schmorp.de>, for more info.
42 49
43WHY YOU SHOULD USE THIS MODULE (OR NOT) 50WHY YOU SHOULD USE THIS MODULE (OR NOT)
44 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 51 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
45 nowadays. So what is different about AnyEvent? 52 nowadays. So what is different about AnyEvent?
46 53
… …
169 176
170 I/O WATCHERS 177 I/O WATCHERS
171 You can create an I/O watcher by calling the "AnyEvent->io" method with 178 You can create an I/O watcher by calling the "AnyEvent->io" method with
172 the following mandatory key-value pairs as arguments: 179 the following mandatory key-value pairs as arguments:
173 180
174 "fh" is the Perl *file handle* (*not* file descriptor) to watch for 181 "fh" is the Perl *file handle* (or a naked file descriptor) to watch for
175 events (AnyEvent might or might not keep a reference to this file 182 events (AnyEvent might or might not keep a reference to this file
176 handle). Note that only file handles pointing to things for which 183 handle). Note that only file handles pointing to things for which
177 non-blocking operation makes sense are allowed. This includes sockets, 184 non-blocking operation makes sense are allowed. This includes sockets,
178 most character devices, pipes, fifos and so on, but not for example 185 most character devices, pipes, fifos and so on, but not for example
179 files or block devices. 186 files or block devices.
… …
350 invocation, and callback invocation will be synchronous. Synchronous 357 invocation, and callback invocation will be synchronous. Synchronous
351 means that it might take a while until the signal gets handled by the 358 means that it might take a while until the signal gets handled by the
352 process, but it is guaranteed not to interrupt any other callbacks. 359 process, but it is guaranteed not to interrupt any other callbacks.
353 360
354 The main advantage of using these watchers is that you can share a 361 The main advantage of using these watchers is that you can share a
355 signal between multiple watchers. 362 signal between multiple watchers, and AnyEvent will ensure that signals
363 will not interrupt your program at bad times.
356 364
357 This watcher might use %SIG, so programs overwriting those signals 365 This watcher might use %SIG (depending on the event loop used), so
358 directly will likely not work correctly. 366 programs overwriting those signals directly will likely not work
367 correctly.
359 368
360 Example: exit on SIGINT 369 Example: exit on SIGINT
361 370
362 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 371 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
372
373 Signal Races, Delays and Workarounds
374 Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
375 callbacks to signals in a generic way, which is a pity, as you cannot do
376 race-free signal handling in perl. AnyEvent will try to do it's best,
377 but in some cases, signals will be delayed. The maximum time a signal
378 might be delayed is specified in $AnyEvent::MAX_SIGNAL_LATENCY (default:
379 10 seconds). This variable can be changed only before the first signal
380 watcher is created, and should be left alone otherwise. Higher values
381 will cause fewer spurious wake-ups, which is better for power and CPU
382 saving. All these problems can be avoided by installing the optional
383 Async::Interrupt module. This will not work with inherently broken event
384 loops such as Event or Event::Lib (and not with POE currently, as POE
385 does it's own workaround with one-second latency). With those, you just
386 have to suffer the delays.
363 387
364 CHILD PROCESS WATCHERS 388 CHILD PROCESS WATCHERS
365 You can also watch on a child process exit and catch its exit status. 389 You can also watch on a child process exit and catch its exit status.
366 390
367 The child process is specified by the "pid" argument (if set to 0, it 391 The child process is specified by the "pid" argument (if set to 0, it
… …
380 404
381 There is a slight catch to child watchers, however: you usually start 405 There is a slight catch to child watchers, however: you usually start
382 them *after* the child process was created, and this means the process 406 them *after* the child process was created, and this means the process
383 could have exited already (and no SIGCHLD will be sent anymore). 407 could have exited already (and no SIGCHLD will be sent anymore).
384 408
385 Not all event models handle this correctly (POE doesn't), but even for 409 Not all event models handle this correctly (neither POE nor IO::Async
410 do, see their AnyEvent::Impl manpages for details), but even for event
386 event models that *do* handle this correctly, they usually need to be 411 models that *do* handle this correctly, they usually need to be loaded
387 loaded before the process exits (i.e. before you fork in the first 412 before the process exits (i.e. before you fork in the first place).
388 place). 413 AnyEvent's pure perl event loop handles all cases correctly regardless
414 of when you start the watcher.
389 415
390 This means you cannot create a child watcher as the very first thing in 416 This means you cannot create a child watcher as the very first thing in
391 an AnyEvent program, you *have* to create at least one watcher before 417 an AnyEvent program, you *have* to create at least one watcher before
392 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 418 you "fork" the child (alternatively, you can call "AnyEvent::detect").
419
420 As most event loops do not support waiting for child events, they will
421 be emulated by AnyEvent in most cases, in which the latency and race
422 problems mentioned in the description of signal watchers apply.
393 423
394 Example: fork a process and wait for it 424 Example: fork a process and wait for it
395 425
396 my $done = AnyEvent->condvar; 426 my $done = AnyEvent->condvar;
397 427
… …
446 CONDITION VARIABLES 476 CONDITION VARIABLES
447 If you are familiar with some event loops you will know that all of them 477 If you are familiar with some event loops you will know that all of them
448 require you to run some blocking "loop", "run" or similar function that 478 require you to run some blocking "loop", "run" or similar function that
449 will actively watch for new events and call your callbacks. 479 will actively watch for new events and call your callbacks.
450 480
451 AnyEvent is different, it expects somebody else to run the event loop 481 AnyEvent is slightly different: it expects somebody else to run the
452 and will only block when necessary (usually when told by the user). 482 event loop and will only block when necessary (usually when told by the
483 user).
453 484
454 The instrument to do that is called a "condition variable", so called 485 The instrument to do that is called a "condition variable", so called
455 because they represent a condition that must become true. 486 because they represent a condition that must become true.
456 487
488 Now is probably a good time to look at the examples further below.
489
457 Condition variables can be created by calling the "AnyEvent->condvar" 490 Condition variables can be created by calling the "AnyEvent->condvar"
458 method, usually without arguments. The only argument pair allowed is 491 method, usually without arguments. The only argument pair allowed is
459
460 "cb", which specifies a callback to be called when the condition 492 "cb", which specifies a callback to be called when the condition
461 variable becomes true, with the condition variable as the first argument 493 variable becomes true, with the condition variable as the first argument
462 (but not the results). 494 (but not the results).
463 495
464 After creation, the condition variable is "false" until it becomes 496 After creation, the condition variable is "false" until it becomes
… …
469 Condition variables are similar to callbacks, except that you can 501 Condition variables are similar to callbacks, except that you can
470 optionally wait for them. They can also be called merge points - points 502 optionally wait for them. They can also be called merge points - points
471 in time where multiple outstanding events have been processed. And yet 503 in time where multiple outstanding events have been processed. And yet
472 another way to call them is transactions - each condition variable can 504 another way to call them is transactions - each condition variable can
473 be used to represent a transaction, which finishes at some point and 505 be used to represent a transaction, which finishes at some point and
474 delivers a result. 506 delivers a result. And yet some people know them as "futures" - a
507 promise to compute/deliver something that you can wait for.
475 508
476 Condition variables are very useful to signal that something has 509 Condition variables are very useful to signal that something has
477 finished, for example, if you write a module that does asynchronous http 510 finished, for example, if you write a module that does asynchronous http
478 requests, then a condition variable would be the ideal candidate to 511 requests, then a condition variable would be the ideal candidate to
479 signal the availability of results. The user can either act when the 512 signal the availability of results. The user can either act when the
… …
513 after => 1, 546 after => 1,
514 cb => sub { $result_ready->send }, 547 cb => sub { $result_ready->send },
515 ); 548 );
516 549
517 # this "blocks" (while handling events) till the callback 550 # this "blocks" (while handling events) till the callback
518 # calls send 551 # calls -<send
519 $result_ready->recv; 552 $result_ready->recv;
520 553
521 Example: wait for a timer, but take advantage of the fact that condition 554 Example: wait for a timer, but take advantage of the fact that condition
522 variables are also code references. 555 variables are also callable directly.
523 556
524 my $done = AnyEvent->condvar; 557 my $done = AnyEvent->condvar;
525 my $delay = AnyEvent->timer (after => 5, cb => $done); 558 my $delay = AnyEvent->timer (after => 5, cb => $done);
526 $done->recv; 559 $done->recv;
527 560
… …
533 566
534 ... 567 ...
535 568
536 my @info = $couchdb->info->recv; 569 my @info = $couchdb->info->recv;
537 570
538 And this is how you would just ste a callback to be called whenever the 571 And this is how you would just set a callback to be called whenever the
539 results are available: 572 results are available:
540 573
541 $couchdb->info->cb (sub { 574 $couchdb->info->cb (sub {
542 my @info = $_[0]->recv; 575 my @info = $_[0]->recv;
543 }); 576 });
… …
558 591
559 Any arguments passed to the "send" call will be returned by all 592 Any arguments passed to the "send" call will be returned by all
560 future "->recv" calls. 593 future "->recv" calls.
561 594
562 Condition variables are overloaded so one can call them directly (as 595 Condition variables are overloaded so one can call them directly (as
563 a code reference). Calling them directly is the same as calling 596 if they were a code reference). Calling them directly is the same as
564 "send". Note, however, that many C-based event loops do not handle 597 calling "send".
565 overloading, so as tempting as it may be, passing a condition
566 variable instead of a callback does not work. Both the pure perl and
567 EV loops support overloading, however, as well as all functions that
568 use perl to invoke a callback (as in AnyEvent::Socket and
569 AnyEvent::DNS for example).
570 598
571 $cv->croak ($error) 599 $cv->croak ($error)
572 Similar to send, but causes all call's to "->recv" to invoke 600 Similar to send, but causes all call's to "->recv" to invoke
573 "Carp::croak" with the given error message/object/scalar. 601 "Carp::croak" with the given error message/object/scalar.
574 602
575 This can be used to signal any errors to the condition variable 603 This can be used to signal any errors to the condition variable
576 user/consumer. 604 user/consumer. Doing it this way instead of calling "croak" directly
605 delays the error detetcion, but has the overwhelmign advantage that
606 it diagnoses the error at the place where the result is expected,
607 and not deep in some event clalback without connection to the actual
608 code causing the problem.
577 609
578 $cv->begin ([group callback]) 610 $cv->begin ([group callback])
579 $cv->end 611 $cv->end
580 These two methods are EXPERIMENTAL and MIGHT CHANGE.
581
582 These two methods can be used to combine many transactions/events 612 These two methods can be used to combine many transactions/events
583 into one. For example, a function that pings many hosts in parallel 613 into one. For example, a function that pings many hosts in parallel
584 might want to use a condition variable for the whole process. 614 might want to use a condition variable for the whole process.
585 615
586 Every call to "->begin" will increment a counter, and every call to 616 Every call to "->begin" will increment a counter, and every call to
587 "->end" will decrement it. If the counter reaches 0 in "->end", the 617 "->end" will decrement it. If the counter reaches 0 in "->end", the
588 (last) callback passed to "begin" will be executed. That callback is 618 (last) callback passed to "begin" will be executed. That callback is
589 *supposed* to call "->send", but that is not required. If no 619 *supposed* to call "->send", but that is not required. If no
590 callback was set, "send" will be called without any arguments. 620 callback was set, "send" will be called without any arguments.
591 621
592 Let's clarify this with the ping example: 622 You can think of "$cv->send" giving you an OR condition (one call
623 sends), while "$cv->begin" and "$cv->end" giving you an AND
624 condition (all "begin" calls must be "end"'ed before the condvar
625 sends).
626
627 Let's start with a simple example: you have two I/O watchers (for
628 example, STDOUT and STDERR for a program), and you want to wait for
629 both streams to close before activating a condvar:
630
631 my $cv = AnyEvent->condvar;
632
633 $cv->begin; # first watcher
634 my $w1 = AnyEvent->io (fh => $fh1, cb => sub {
635 defined sysread $fh1, my $buf, 4096
636 or $cv->end;
637 });
638
639 $cv->begin; # second watcher
640 my $w2 = AnyEvent->io (fh => $fh2, cb => sub {
641 defined sysread $fh2, my $buf, 4096
642 or $cv->end;
643 });
644
645 $cv->recv;
646
647 This works because for every event source (EOF on file handle),
648 there is one call to "begin", so the condvar waits for all calls to
649 "end" before sending.
650
651 The ping example mentioned above is slightly more complicated, as
652 the there are results to be passwd back, and the number of tasks
653 that are begung can potentially be zero:
593 654
594 my $cv = AnyEvent->condvar; 655 my $cv = AnyEvent->condvar;
595 656
596 my %result; 657 my %result;
597 $cv->begin (sub { $cv->send (\%result) }); 658 $cv->begin (sub { $cv->send (\%result) });
… …
617 the loop, which serves two important purposes: first, it sets the 678 the loop, which serves two important purposes: first, it sets the
618 callback to be called once the counter reaches 0, and second, it 679 callback to be called once the counter reaches 0, and second, it
619 ensures that "send" is called even when "no" hosts are being pinged 680 ensures that "send" is called even when "no" hosts are being pinged
620 (the loop doesn't execute once). 681 (the loop doesn't execute once).
621 682
622 This is the general pattern when you "fan out" into multiple 683 This is the general pattern when you "fan out" into multiple (but
623 subrequests: use an outer "begin"/"end" pair to set the callback and 684 potentially none) subrequests: use an outer "begin"/"end" pair to
624 ensure "end" is called at least once, and then, for each subrequest 685 set the callback and ensure "end" is called at least once, and then,
625 you start, call "begin" and for each subrequest you finish, call 686 for each subrequest you start, call "begin" and for each subrequest
626 "end". 687 you finish, call "end".
627 688
628 METHODS FOR CONSUMERS 689 METHODS FOR CONSUMERS
629 These methods should only be used by the consuming side, i.e. the code 690 These methods should only be used by the consuming side, i.e. the code
630 awaits the condition. 691 awaits the condition.
631 692
… …
640 function will call "croak". 701 function will call "croak".
641 702
642 In list context, all parameters passed to "send" will be returned, 703 In list context, all parameters passed to "send" will be returned,
643 in scalar context only the first one will be returned. 704 in scalar context only the first one will be returned.
644 705
706 Note that doing a blocking wait in a callback is not supported by
707 any event loop, that is, recursive invocation of a blocking "->recv"
708 is not allowed, and the "recv" call will "croak" if such a condition
709 is detected. This condition can be slightly loosened by using
710 Coro::AnyEvent, which allows you to do a blocking "->recv" from any
711 thread that doesn't run the event loop itself.
712
645 Not all event models support a blocking wait - some die in that case 713 Not all event models support a blocking wait - some die in that case
646 (programs might want to do that to stay interactive), so *if you are 714 (programs might want to do that to stay interactive), so *if you are
647 using this from a module, never require a blocking wait*, but let 715 using this from a module, never require a blocking wait*. Instead,
648 the caller decide whether the call will block or not (for example, 716 let the caller decide whether the call will block or not (for
649 by coupling condition variables with some kind of request results 717 example, by coupling condition variables with some kind of request
650 and supporting callbacks so the caller knows that getting the result 718 results and supporting callbacks so the caller knows that getting
651 will not block, while still supporting blocking waits if the caller 719 the result will not block, while still supporting blocking waits if
652 so desires). 720 the caller so desires).
653
654 Another reason *never* to "->recv" in a module is that you cannot
655 sensibly have two "->recv"'s in parallel, as that would require
656 multiple interpreters or coroutines/threads, none of which
657 "AnyEvent" can supply.
658
659 The Coro module, however, *can* and *does* supply coroutines and, in
660 fact, Coro::AnyEvent replaces AnyEvent's condvars by coroutine-safe
661 versions and also integrates coroutines into AnyEvent, making
662 blocking "->recv" calls perfectly safe as long as they are done from
663 another coroutine (one that doesn't run the event loop).
664 721
665 You can ensure that "-recv" never blocks by setting a callback and 722 You can ensure that "-recv" never blocks by setting a callback and
666 only calling "->recv" from within that callback (or at a later 723 only calling "->recv" from within that callback (or at a later
667 time). This will work even when the event loop does not support 724 time). This will work even when the event loop does not support
668 blocking waits otherwise. 725 blocking waits otherwise.
… …
678 The callback will be called when the condition becomes "true", i.e. 735 The callback will be called when the condition becomes "true", i.e.
679 when "send" or "croak" are called, with the only argument being the 736 when "send" or "croak" are called, with the only argument being the
680 condition variable itself. Calling "recv" inside the callback or at 737 condition variable itself. Calling "recv" inside the callback or at
681 any later time is guaranteed not to block. 738 any later time is guaranteed not to block.
682 739
740SUPPORTED EVENT LOOPS/BACKENDS
741 The available backend classes are (every class has its own manpage):
742
743 Backends that are autoprobed when no other event loop can be found.
744 EV is the preferred backend when no other event loop seems to be in
745 use. If EV is not installed, then AnyEvent will try Event, and,
746 failing that, will fall back to its own pure-perl implementation,
747 which is available everywhere as it comes with AnyEvent itself.
748
749 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
750 AnyEvent::Impl::Event based on Event, very stable, few glitches.
751 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
752
753 Backends that are transparently being picked up when they are used.
754 These will be used when they are currently loaded when the first
755 watcher is created, in which case it is assumed that the application
756 is using them. This means that AnyEvent will automatically pick the
757 right backend when the main program loads an event module before
758 anything starts to create watchers. Nothing special needs to be done
759 by the main program.
760
761 AnyEvent::Impl::Glib based on Glib, slow but very stable.
762 AnyEvent::Impl::Tk based on Tk, very broken.
763 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
764 AnyEvent::Impl::POE based on POE, very slow, some limitations.
765
766 Backends with special needs.
767 Qt requires the Qt::Application to be instantiated first, but will
768 otherwise be picked up automatically. As long as the main program
769 instantiates the application before any AnyEvent watchers are
770 created, everything should just work.
771
772 AnyEvent::Impl::Qt based on Qt.
773
774 Support for IO::Async can only be partial, as it is too broken and
775 architecturally limited to even support the AnyEvent API. It also is
776 the only event loop that needs the loop to be set explicitly, so it
777 can only be used by a main program knowing about AnyEvent. See
778 AnyEvent::Impl::Async for the gory details.
779
780 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed.
781
782 Event loops that are indirectly supported via other backends.
783 Some event loops can be supported via other modules:
784
785 There is no direct support for WxWidgets (Wx) or Prima.
786
787 WxWidgets has no support for watching file handles. However, you can
788 use WxWidgets through the POE adaptor, as POE has a Wx backend that
789 simply polls 20 times per second, which was considered to be too
790 horrible to even consider for AnyEvent.
791
792 Prima is not supported as nobody seems to be using it, but it has a
793 POE backend, so it can be supported through POE.
794
795 AnyEvent knows about both Prima and Wx, however, and will try to
796 load POE when detecting them, in the hope that POE will pick them
797 up, in which case everything will be automatic.
798
683GLOBAL VARIABLES AND FUNCTIONS 799GLOBAL VARIABLES AND FUNCTIONS
800 These are not normally required to use AnyEvent, but can be useful to
801 write AnyEvent extension modules.
802
684 $AnyEvent::MODEL 803 $AnyEvent::MODEL
685 Contains "undef" until the first watcher is being created. Then it 804 Contains "undef" until the first watcher is being created, before
805 the backend has been autodetected.
806
686 contains the event model that is being used, which is the name of 807 Afterwards it contains the event model that is being used, which is
687 the Perl class implementing the model. This class is usually one of 808 the name of the Perl class implementing the model. This class is
688 the "AnyEvent::Impl:xxx" modules, but can be any other class in the 809 usually one of the "AnyEvent::Impl:xxx" modules, but can be any
689 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). 810 other class in the case AnyEvent has been extended at runtime (e.g.
690 811 in *rxvt-unicode* it will be "urxvt::anyevent").
691 The known classes so far are:
692
693 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
694 AnyEvent::Impl::Event based on Event, second best choice.
695 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
696 AnyEvent::Impl::Glib based on Glib, third-best choice.
697 AnyEvent::Impl::Tk based on Tk, very bad choice.
698 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
699 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
700 AnyEvent::Impl::POE based on POE, not generic enough for full support.
701
702 There is no support for WxWidgets, as WxWidgets has no support for
703 watching file handles. However, you can use WxWidgets through the
704 POE Adaptor, as POE has a Wx backend that simply polls 20 times per
705 second, which was considered to be too horrible to even consider for
706 AnyEvent. Likewise, other POE backends can be used by AnyEvent by
707 using it's adaptor.
708
709 AnyEvent knows about Prima and Wx and will try to use POE when
710 autodetecting them.
711 812
712 AnyEvent::detect 813 AnyEvent::detect
713 Returns $AnyEvent::MODEL, forcing autodetection of the event model 814 Returns $AnyEvent::MODEL, forcing autodetection of the event model
714 if necessary. You should only call this function right before you 815 if necessary. You should only call this function right before you
715 would have created an AnyEvent watcher anyway, that is, as late as 816 would have created an AnyEvent watcher anyway, that is, as late as
716 possible at runtime. 817 possible at runtime, and not e.g. while initialising of your module.
818
819 If you need to do some initialisation before AnyEvent watchers are
820 created, use "post_detect".
717 821
718 $guard = AnyEvent::post_detect { BLOCK } 822 $guard = AnyEvent::post_detect { BLOCK }
719 Arranges for the code block to be executed as soon as the event 823 Arranges for the code block to be executed as soon as the event
720 model is autodetected (or immediately if this has already happened). 824 model is autodetected (or immediately if this has already happened).
825
826 The block will be executed *after* the actual backend has been
827 detected ($AnyEvent::MODEL is set), but *before* any watchers have
828 been created, so it is possible to e.g. patch @AnyEvent::ISA or do
829 other initialisations - see the sources of AnyEvent::Strict or
830 AnyEvent::AIO to see how this is used.
831
832 The most common usage is to create some global watchers, without
833 forcing event module detection too early, for example, AnyEvent::AIO
834 creates and installs the global IO::AIO watcher in a "post_detect"
835 block to avoid autodetecting the event module at load time.
721 836
722 If called in scalar or list context, then it creates and returns an 837 If called in scalar or list context, then it creates and returns an
723 object that automatically removes the callback again when it is 838 object that automatically removes the callback again when it is
724 destroyed. See Coro::BDB for a case where this is useful. 839 destroyed. See Coro::BDB for a case where this is useful.
725 840
… …
727 If there are any code references in this array (you can "push" to it 842 If there are any code references in this array (you can "push" to it
728 before or after loading AnyEvent), then they will called directly 843 before or after loading AnyEvent), then they will called directly
729 after the event loop has been chosen. 844 after the event loop has been chosen.
730 845
731 You should check $AnyEvent::MODEL before adding to this array, 846 You should check $AnyEvent::MODEL before adding to this array,
732 though: if it contains a true value then the event loop has already 847 though: if it is defined then the event loop has already been
733 been detected, and the array will be ignored. 848 detected, and the array will be ignored.
734 849
735 Best use "AnyEvent::post_detect { BLOCK }" instead. 850 Best use "AnyEvent::post_detect { BLOCK }" when your application
851 allows it,as it takes care of these details.
852
853 This variable is mainly useful for modules that can do something
854 useful when AnyEvent is used and thus want to know when it is
855 initialised, but do not need to even load it by default. This array
856 provides the means to hook into AnyEvent passively, without loading
857 it.
736 858
737WHAT TO DO IN A MODULE 859WHAT TO DO IN A MODULE
738 As a module author, you should "use AnyEvent" and call AnyEvent methods 860 As a module author, you should "use AnyEvent" and call AnyEvent methods
739 freely, but you should not load a specific event module or rely on it. 861 freely, but you should not load a specific event module or rely on it.
740 862
… …
791 variable somewhere, waiting for it, and sending it when the program 913 variable somewhere, waiting for it, and sending it when the program
792 should exit cleanly. 914 should exit cleanly.
793 915
794OTHER MODULES 916OTHER MODULES
795 The following is a non-exhaustive list of additional modules that use 917 The following is a non-exhaustive list of additional modules that use
796 AnyEvent and can therefore be mixed easily with other AnyEvent modules 918 AnyEvent as a client and can therefore be mixed easily with other
797 in the same program. Some of the modules come with AnyEvent, some are 919 AnyEvent modules and other event loops in the same program. Some of the
798 available via CPAN. 920 modules come with AnyEvent, most are available via CPAN.
799 921
800 AnyEvent::Util 922 AnyEvent::Util
801 Contains various utility functions that replace often-used but 923 Contains various utility functions that replace often-used but
802 blocking functions such as "inet_aton" by event-/callback-based 924 blocking functions such as "inet_aton" by event-/callback-based
803 versions. 925 versions.
… …
809 more. 931 more.
810 932
811 AnyEvent::Handle 933 AnyEvent::Handle
812 Provide read and write buffers, manages watchers for reads and 934 Provide read and write buffers, manages watchers for reads and
813 writes, supports raw and formatted I/O, I/O queued and fully 935 writes, supports raw and formatted I/O, I/O queued and fully
814 transparent and non-blocking SSL/TLS. 936 transparent and non-blocking SSL/TLS (via AnyEvent::TLS.
815 937
816 AnyEvent::DNS 938 AnyEvent::DNS
817 Provides rich asynchronous DNS resolver capabilities. 939 Provides rich asynchronous DNS resolver capabilities.
818 940
819 AnyEvent::HTTP 941 AnyEvent::HTTP
… …
840 962
841 AnyEvent::GPSD 963 AnyEvent::GPSD
842 A non-blocking interface to gpsd, a daemon delivering GPS 964 A non-blocking interface to gpsd, a daemon delivering GPS
843 information. 965 information.
844 966
967 AnyEvent::IRC
968 AnyEvent based IRC client module family (replacing the older
969 Net::IRC3).
970
971 AnyEvent::XMPP
972 AnyEvent based XMPP (Jabber protocol) module family (replacing the
973 older Net::XMPP2>.
974
845 AnyEvent::IGS 975 AnyEvent::IGS
846 A non-blocking interface to the Internet Go Server protocol (used by 976 A non-blocking interface to the Internet Go Server protocol (used by
847 App::IGS). 977 App::IGS).
848 978
849 AnyEvent::IRC
850 AnyEvent based IRC client module family (replacing the older
851 Net::IRC3).
852
853 Net::XMPP2
854 AnyEvent based XMPP (Jabber protocol) module family.
855
856 Net::FCP 979 Net::FCP
857 AnyEvent-based implementation of the Freenet Client Protocol, 980 AnyEvent-based implementation of the Freenet Client Protocol,
858 birthplace of AnyEvent. 981 birthplace of AnyEvent.
859 982
860 Event::ExecFlow 983 Event::ExecFlow
861 High level API for event-based execution flow control. 984 High level API for event-based execution flow control.
862 985
863 Coro 986 Coro
864 Has special support for AnyEvent via Coro::AnyEvent. 987 Has special support for AnyEvent via Coro::AnyEvent.
865
866 IO::Lambda
867 The lambda approach to I/O - don't ask, look there. Can use
868 AnyEvent.
869 988
870ERROR AND EXCEPTION HANDLING 989ERROR AND EXCEPTION HANDLING
871 In general, AnyEvent does not do any error handling - it relies on the 990 In general, AnyEvent does not do any error handling - it relies on the
872 caller to do that if required. The AnyEvent::Strict module (see also the 991 caller to do that if required. The AnyEvent::Strict module (see also the
873 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict 992 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
… …
901 by "PERL_ANYEVENT_MODEL". 1020 by "PERL_ANYEVENT_MODEL".
902 1021
903 When set to 2 or higher, cause AnyEvent to report to STDERR which 1022 When set to 2 or higher, cause AnyEvent to report to STDERR which
904 event model it chooses. 1023 event model it chooses.
905 1024
1025 When set to 8 or higher, then AnyEvent will report extra information
1026 on which optional modules it loads and how it implements certain
1027 features.
1028
906 "PERL_ANYEVENT_STRICT" 1029 "PERL_ANYEVENT_STRICT"
907 AnyEvent does not do much argument checking by default, as thorough 1030 AnyEvent does not do much argument checking by default, as thorough
908 argument checking is very costly. Setting this variable to a true 1031 argument checking is very costly. Setting this variable to a true
909 value will cause AnyEvent to load "AnyEvent::Strict" and then to 1032 value will cause AnyEvent to load "AnyEvent::Strict" and then to
910 thoroughly check the arguments passed to most method calls. If it 1033 thoroughly check the arguments passed to most method calls. If it
911 finds any problems it will croak. 1034 finds any problems, it will croak.
912 1035
913 In other words, enables "strict" mode. 1036 In other words, enables "strict" mode.
914 1037
915 Unlike "use strict", it is definitely recommended ot keep it off in 1038 Unlike "use strict" (or it's modern cousin, "use common::sense", it
916 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment 1039 is definitely recommended to keep it off in production. Keeping
1040 "PERL_ANYEVENT_STRICT=1" in your environment while developing
917 while developing programs can be very useful, however. 1041 programs can be very useful, however.
918 1042
919 "PERL_ANYEVENT_MODEL" 1043 "PERL_ANYEVENT_MODEL"
920 This can be used to specify the event model to be used by AnyEvent, 1044 This can be used to specify the event model to be used by AnyEvent,
921 before auto detection and -probing kicks in. It must be a string 1045 before auto detection and -probing kicks in. It must be a string
922 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 1046 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
963 EDNS0 in its DNS requests. 1087 EDNS0 in its DNS requests.
964 1088
965 "PERL_ANYEVENT_MAX_FORKS" 1089 "PERL_ANYEVENT_MAX_FORKS"
966 The maximum number of child processes that 1090 The maximum number of child processes that
967 "AnyEvent::Util::fork_call" will create in parallel. 1091 "AnyEvent::Util::fork_call" will create in parallel.
1092
1093 "PERL_ANYEVENT_MAX_OUTSTANDING_DNS"
1094 The default value for the "max_outstanding" parameter for the
1095 default DNS resolver - this is the maximum number of parallel DNS
1096 requests that are sent to the DNS server.
1097
1098 "PERL_ANYEVENT_RESOLV_CONF"
1099 The file to use instead of /etc/resolv.conf (or OS-specific
1100 configuration) in the default resolver. When set to the empty
1101 string, no default config will be used.
1102
1103 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH".
1104 When neither "ca_file" nor "ca_path" was specified during
1105 AnyEvent::TLS context creation, and either of these environment
1106 variables exist, they will be used to specify CA certificate
1107 locations instead of a system-dependent default.
1108
1109 "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT"
1110 When these are set to 1, then the respective modules are not loaded.
1111 Mostly good for testing AnyEvent itself.
968 1112
969SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1113SUPPLYING YOUR OWN EVENT MODEL INTERFACE
970 This is an advanced topic that you do not normally need to use AnyEvent 1114 This is an advanced topic that you do not normally need to use AnyEvent
971 in a module. This section is only of use to event loop authors who want 1115 in a module. This section is only of use to event loop authors who want
972 to provide AnyEvent compatibility. 1116 to provide AnyEvent compatibility.
… …
1208 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers 1352 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
1209 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal 1353 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
1210 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation 1354 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
1211 Event/Event 16000 517 32.20 31.80 0.81 Event native interface 1355 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
1212 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers 1356 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
1357 IOAsync/Any 16000 989 38.10 32.77 11.13 via IO::Async::Loop::IO_Poll
1358 IOAsync/Any 16000 990 37.59 29.50 10.61 via IO::Async::Loop::Epoll
1213 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour 1359 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
1214 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers 1360 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
1215 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event 1361 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
1216 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select 1362 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
1217 1363
… …
1246 few of them active), of course, but this was not subject of this 1392 few of them active), of course, but this was not subject of this
1247 benchmark. 1393 benchmark.
1248 1394
1249 The "Event" module has a relatively high setup and callback invocation 1395 The "Event" module has a relatively high setup and callback invocation
1250 cost, but overall scores in on the third place. 1396 cost, but overall scores in on the third place.
1397
1398 "IO::Async" performs admirably well, about on par with "Event", even
1399 when using its pure perl backend.
1251 1400
1252 "Glib"'s memory usage is quite a bit higher, but it features a faster 1401 "Glib"'s memory usage is quite a bit higher, but it features a faster
1253 callback invocation and overall ends up in the same class as "Event". 1402 callback invocation and overall ends up in the same class as "Event".
1254 However, Glib scales extremely badly, doubling the number of watchers 1403 However, Glib scales extremely badly, doubling the number of watchers
1255 increases the processing time by more than a factor of four, making it 1404 increases the processing time by more than a factor of four, making it
… …
1326 single "request", that is, reading the token from the pipe and 1475 single "request", that is, reading the token from the pipe and
1327 forwarding it to another server. This includes deleting the old timeout 1476 forwarding it to another server. This includes deleting the old timeout
1328 and creating a new one that moves the timeout into the future. 1477 and creating a new one that moves the timeout into the future.
1329 1478
1330 Results 1479 Results
1331 name sockets create request 1480 name sockets create request
1332 EV 20000 69.01 11.16 1481 EV 20000 69.01 11.16
1333 Perl 20000 73.32 35.87 1482 Perl 20000 73.32 35.87
1483 IOAsync 20000 157.00 98.14 epoll
1484 IOAsync 20000 159.31 616.06 poll
1334 Event 20000 212.62 257.32 1485 Event 20000 212.62 257.32
1335 Glib 20000 651.16 1896.30 1486 Glib 20000 651.16 1896.30
1336 POE 20000 349.67 12317.24 uses POE::Loop::Event 1487 POE 20000 349.67 12317.24 uses POE::Loop::Event
1337 1488
1338 Discussion 1489 Discussion
1339 This benchmark *does* measure scalability and overall performance of the 1490 This benchmark *does* measure scalability and overall performance of the
1340 particular event loop. 1491 particular event loop.
1341 1492
1342 EV is again fastest. Since it is using epoll on my system, the setup 1493 EV is again fastest. Since it is using epoll on my system, the setup
1343 time is relatively high, though. 1494 time is relatively high, though.
1344 1495
1345 Perl surprisingly comes second. It is much faster than the C-based event 1496 Perl surprisingly comes second. It is much faster than the C-based event
1346 loops Event and Glib. 1497 loops Event and Glib.
1498
1499 IO::Async performs very well when using its epoll backend, and still
1500 quite good compared to Glib when using its pure perl backend.
1347 1501
1348 Event suffers from high setup time as well (look at its code and you 1502 Event suffers from high setup time as well (look at its code and you
1349 will understand why). Callback invocation also has a high overhead 1503 will understand why). Callback invocation also has a high overhead
1350 compared to the "$_->() for .."-style loop that the Perl event loop 1504 compared to the "$_->() for .."-style loop that the Perl event loop
1351 uses. Event uses select or poll in basically all documented 1505 uses. Event uses select or poll in basically all documented
… …
1407 THE IO::Lambda BENCHMARK 1561 THE IO::Lambda BENCHMARK
1408 Recently I was told about the benchmark in the IO::Lambda manpage, which 1562 Recently I was told about the benchmark in the IO::Lambda manpage, which
1409 could be misinterpreted to make AnyEvent look bad. In fact, the 1563 could be misinterpreted to make AnyEvent look bad. In fact, the
1410 benchmark simply compares IO::Lambda with POE, and IO::Lambda looks 1564 benchmark simply compares IO::Lambda with POE, and IO::Lambda looks
1411 better (which shouldn't come as a surprise to anybody). As such, the 1565 better (which shouldn't come as a surprise to anybody). As such, the
1412 benchmark is fine, and shows that the AnyEvent backend from IO::Lambda 1566 benchmark is fine, and mostly shows that the AnyEvent backend from
1413 isn't very optimal. But how would AnyEvent compare when used without the 1567 IO::Lambda isn't very optimal. But how would AnyEvent compare when used
1414 extra baggage? To explore this, I wrote the equivalent benchmark for 1568 without the extra baggage? To explore this, I wrote the equivalent
1415 AnyEvent. 1569 benchmark for AnyEvent.
1416 1570
1417 The benchmark itself creates an echo-server, and then, for 500 times, 1571 The benchmark itself creates an echo-server, and then, for 500 times,
1418 connects to the echo server, sends a line, waits for the reply, and then 1572 connects to the echo server, sends a line, waits for the reply, and then
1419 creates the next connection. This is a rather bad benchmark, as it 1573 creates the next connection. This is a rather bad benchmark, as it
1420 doesn't test the efficiency of the framework, but it is a benchmark 1574 doesn't test the efficiency of the framework or much non-blocking I/O,
1421 nevertheless. 1575 but it is a benchmark nevertheless.
1422 1576
1423 name runtime 1577 name runtime
1424 Lambda/select 0.330 sec 1578 Lambda/select 0.330 sec
1425 + optimized 0.122 sec 1579 + optimized 0.122 sec
1426 Lambda/AnyEvent 0.327 sec 1580 Lambda/AnyEvent 0.327 sec
… …
1432 1586
1433 AnyEvent/select/nb 0.085 sec 1587 AnyEvent/select/nb 0.085 sec
1434 AnyEvent/EV/nb 0.068 sec 1588 AnyEvent/EV/nb 0.068 sec
1435 +state machine 0.134 sec 1589 +state machine 0.134 sec
1436 1590
1437 The benchmark is also a bit unfair (my fault) - the IO::Lambda 1591 The benchmark is also a bit unfair (my fault): the IO::Lambda/POE
1438 benchmarks actually make blocking connects and use 100% blocking I/O, 1592 benchmarks actually make blocking connects and use 100% blocking I/O,
1439 defeating the purpose of an event-based solution. All of the newly 1593 defeating the purpose of an event-based solution. All of the newly
1440 written AnyEvent benchmarks use 100% non-blocking connects (using 1594 written AnyEvent benchmarks use 100% non-blocking connects (using
1441 AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS 1595 AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS
1442 resolver), so AnyEvent is at a disadvantage here as non-blocking 1596 resolver), so AnyEvent is at a disadvantage here, as non-blocking
1443 connects generally require a lot more bookkeeping and event handling 1597 connects generally require a lot more bookkeeping and event handling
1444 than blocking connects (which involve a single syscall only). 1598 than blocking connects (which involve a single syscall only).
1445 1599
1446 The last AnyEvent benchmark additionally uses AnyEvent::Handle, which 1600 The last AnyEvent benchmark additionally uses AnyEvent::Handle, which
1447 offers similar expressive power as POE and IO::Lambda (using 1601 offers similar expressive power as POE and IO::Lambda, using
1448 conventional Perl syntax), which means both the echo server and the 1602 conventional Perl syntax. This means that both the echo server and the
1449 client are 100% non-blocking w.r.t. I/O, further placing it at a 1603 client are 100% non-blocking, further placing it at a disadvantage.
1450 disadvantage.
1451 1604
1452 As you can see, AnyEvent + EV even beats the hand-optimised "raw sockets 1605 As you can see, the AnyEvent + EV combination even beats the
1453 benchmark", while AnyEvent + its pure perl backend easily beats 1606 hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
1454 IO::Lambda and POE. 1607 backend easily beats IO::Lambda and POE.
1455 1608
1456 And even the 100% non-blocking version written using the high-level (and 1609 And even the 100% non-blocking version written using the high-level (and
1457 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda, even 1610 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda by a
1458 thought it does all of DNS, tcp-connect and socket I/O in a non-blocking 1611 large margin, even though it does all of DNS, tcp-connect and socket I/O
1459 way. 1612 in a non-blocking way.
1460 1613
1461 The two AnyEvent benchmarks can be found as eg/ae0.pl and eg/ae2.pl in 1614 The two AnyEvent benchmarks programs can be found as eg/ae0.pl and
1462 the AnyEvent distribution, the remaining benchmarks are part of the 1615 eg/ae2.pl in the AnyEvent distribution, the remaining benchmarks are
1463 IO::lambda distribution and were used without any changes. 1616 part of the IO::lambda distribution and were used without any changes.
1464 1617
1465SIGNALS 1618SIGNALS
1466 AnyEvent currently installs handlers for these signals: 1619 AnyEvent currently installs handlers for these signals:
1467 1620
1468 SIGCHLD 1621 SIGCHLD
1469 A handler for "SIGCHLD" is installed by AnyEvent's child watcher 1622 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1470 emulation for event loops that do not support them natively. Also, 1623 emulation for event loops that do not support them natively. Also,
1471 some event loops install a similar handler. 1624 some event loops install a similar handler.
1625
1626 Additionally, when AnyEvent is loaded and SIGCHLD is set to IGNORE,
1627 then AnyEvent will reset it to default, to avoid losing child exit
1628 statuses.
1472 1629
1473 SIGPIPE 1630 SIGPIPE
1474 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is 1631 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1475 "undef" when AnyEvent gets loaded. 1632 "undef" when AnyEvent gets loaded.
1476 1633
… …
1484 it is that this way, the handler will be restored to defaults on 1641 it is that this way, the handler will be restored to defaults on
1485 exec. 1642 exec.
1486 1643
1487 Feel free to install your own handler, or reset it to defaults. 1644 Feel free to install your own handler, or reset it to defaults.
1488 1645
1646RECOMMENDED/OPTIONAL MODULES
1647 One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
1648 it's built-in modules) are required to use it.
1649
1650 That does not mean that AnyEvent won't take advantage of some additional
1651 modules if they are installed.
1652
1653 This section epxlains which additional modules will be used, and how
1654 they affect AnyEvent's operetion.
1655
1656 Async::Interrupt
1657 This slightly arcane module is used to implement fast signal
1658 handling: To my knowledge, there is no way to do completely
1659 race-free and quick signal handling in pure perl. To ensure that
1660 signals still get delivered, AnyEvent will start an interval timer
1661 to wake up perl (and catch the signals) with some delay (default is
1662 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY).
1663
1664 If this module is available, then it will be used to implement
1665 signal catching, which means that signals will not be delayed, and
1666 the event loop will not be interrupted regularly, which is more
1667 efficient (And good for battery life on laptops).
1668
1669 This affects not just the pure-perl event loop, but also other event
1670 loops that have no signal handling on their own (e.g. Glib, Tk, Qt).
1671
1672 Some event loops (POE, Event, Event::Lib) offer signal watchers
1673 natively, and either employ their own workarounds (POE) or use
1674 AnyEvent's workaround (using $AnyEvent::MAX_SIGNAL_LATENCY).
1675 Installing Async::Interrupt does nothing for those backends.
1676
1677 EV This module isn't really "optional", as it is simply one of the
1678 backend event loops that AnyEvent can use. However, it is simply the
1679 best event loop available in terms of features, speed and stability:
1680 It supports the AnyEvent API optimally, implements all the watcher
1681 types in XS, does automatic timer adjustments even when no monotonic
1682 clock is available, can take avdantage of advanced kernel interfaces
1683 such as "epoll" and "kqueue", and is the fastest backend *by far*.
1684 You can even embed Glib/Gtk2 in it (or vice versa, see EV::Glib and
1685 Glib::EV).
1686
1687 Guard
1688 The guard module, when used, will be used to implement
1689 "AnyEvent::Util::guard". This speeds up guards considerably (and
1690 uses a lot less memory), but otherwise doesn't affect guard
1691 operation much. It is purely used for performance.
1692
1693 JSON and JSON::XS
1694 This module is required when you want to read or write JSON data via
1695 AnyEvent::Handle. It is also written in pure-perl, but can take
1696 advantage of the ultra-high-speed JSON::XS module when it is
1697 installed.
1698
1699 In fact, AnyEvent::Handle will use JSON::XS by default if it is
1700 installed.
1701
1702 Net::SSLeay
1703 Implementing TLS/SSL in Perl is certainly interesting, but not very
1704 worthwhile: If this module is installed, then AnyEvent::Handle (with
1705 the help of AnyEvent::TLS), gains the ability to do TLS/SSL.
1706
1707 Time::HiRes
1708 This module is part of perl since release 5.008. It will be used
1709 when the chosen event library does not come with a timing source on
1710 it's own. The pure-perl event loop (AnyEvent::Impl::Perl) will
1711 additionally use it to try to use a monotonic clock for timing
1712 stability.
1713
1489FORK 1714FORK
1490 Most event libraries are not fork-safe. The ones who are usually are 1715 Most event libraries are not fork-safe. The ones who are usually are
1491 because they rely on inefficient but fork-safe "select" or "poll" calls. 1716 because they rely on inefficient but fork-safe "select" or "poll" calls.
1492 Only EV is fully fork-aware. 1717 Only EV is fully fork-aware.
1493 1718
1494 If you have to fork, you must either do so *before* creating your first 1719 If you have to fork, you must either do so *before* creating your first
1495 watcher OR you must not use AnyEvent at all in the child. 1720 watcher OR you must not use AnyEvent at all in the child OR you must do
1721 something completely out of the scope of AnyEvent.
1496 1722
1497SECURITY CONSIDERATIONS 1723SECURITY CONSIDERATIONS
1498 AnyEvent can be forced to load any event model via 1724 AnyEvent can be forced to load any event model via
1499 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used 1725 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
1500 to execute arbitrary code or directly gain access, it can easily be used 1726 to execute arbitrary code or directly gain access, it can easily be used
… …
1512 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1738 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1513 be used to probe what backend is used and gain other information (which 1739 be used to probe what backend is used and gain other information (which
1514 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL), 1740 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
1515 and $ENV{PERL_ANYEVENT_STRICT}. 1741 and $ENV{PERL_ANYEVENT_STRICT}.
1516 1742
1743 Note that AnyEvent will remove *all* environment variables starting with
1744 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
1745 enabled.
1746
1517BUGS 1747BUGS
1518 Perl 5.8 has numerous memleaks that sometimes hit this module and are 1748 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1519 hard to work around. If you suffer from memleaks, first upgrade to Perl 1749 hard to work around. If you suffer from memleaks, first upgrade to Perl
1520 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other 1750 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
1521 annoying memleaks, such as leaking on "map" and "grep" but it is usually 1751 annoying memleaks, such as leaking on "map" and "grep" but it is usually
… …
1527 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, 1757 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
1528 Event::Lib, Qt, POE. 1758 Event::Lib, Qt, POE.
1529 1759
1530 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, 1760 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1531 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, 1761 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1532 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE. 1762 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
1763 AnyEvent::Impl::IOAsync.
1533 1764
1534 Non-blocking file handles, sockets, TCP clients and servers: 1765 Non-blocking file handles, sockets, TCP clients and servers:
1535 AnyEvent::Handle, AnyEvent::Socket. 1766 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1536 1767
1537 Asynchronous DNS: AnyEvent::DNS. 1768 Asynchronous DNS: AnyEvent::DNS.
1538 1769
1539 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, 1770 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1540 1771
1541 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS. 1772 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::XMPP,
1773 AnyEvent::HTTP.
1542 1774
1543AUTHOR 1775AUTHOR
1544 Marc Lehmann <schmorp@schmorp.de> 1776 Marc Lehmann <schmorp@schmorp.de>
1545 http://home.schmorp.de/ 1777 http://home.schmorp.de/
1546 1778

Diff Legend

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