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

Comparing AnyEvent/README (file contents):
Revision 1.42 by root, Mon Jun 29 21:00:32 2009 UTC vs.
Revision 1.49 by root, Tue Jul 28 11:02:19 2009 UTC

1NAME 1NAME
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - the DBI of event loop programming
3 3
4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported 4 EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async,
5 event loops. 5 Qt and POE are various supported event loops/environments.
6 6
7SYNOPSIS 7SYNOPSIS
8 use AnyEvent; 8 use AnyEvent;
9 9
10 # file descriptor readable 10 # file descriptor readable
… …
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 Repository, 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 (one some backends,
368 watches for any child process exit). The watcher will triggered only 392 using 0 watches for any child process exit, on others this will croak).
369 when the child process has finished and an exit status is available, not 393 The watcher will be triggered only when the child process has finished
370 on any trace events (stopped/continued). 394 and an exit status is available, not on any trace events
395 (stopped/continued).
371 396
372 The callback will be called with the pid and exit status (as returned by 397 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 398 waitpid), so unlike other watcher types, you *can* rely on child watcher
374 callback arguments. 399 callback arguments.
375 400
… …
390 of when you start the watcher. 415 of when you start the watcher.
391 416
392 This means you cannot create a child watcher as the very first thing in 417 This means you cannot create a child watcher as the very first thing in
393 an AnyEvent program, you *have* to create at least one watcher before 418 an AnyEvent program, you *have* to create at least one watcher before
394 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 419 you "fork" the child (alternatively, you can call "AnyEvent::detect").
420
421 As most event loops do not support waiting for child events, they will
422 be emulated by AnyEvent in most cases, in which the latency and race
423 problems mentioned in the description of signal watchers apply.
395 424
396 Example: fork a process and wait for it 425 Example: fork a process and wait for it
397 426
398 my $done = AnyEvent->condvar; 427 my $done = AnyEvent->condvar;
399 428
… …
448 CONDITION VARIABLES 477 CONDITION VARIABLES
449 If you are familiar with some event loops you will know that all of them 478 If you are familiar with some event loops you will know that all of them
450 require you to run some blocking "loop", "run" or similar function that 479 require you to run some blocking "loop", "run" or similar function that
451 will actively watch for new events and call your callbacks. 480 will actively watch for new events and call your callbacks.
452 481
453 AnyEvent is different, it expects somebody else to run the event loop 482 AnyEvent is slightly different: it expects somebody else to run the
454 and will only block when necessary (usually when told by the user). 483 event loop and will only block when necessary (usually when told by the
484 user).
455 485
456 The instrument to do that is called a "condition variable", so called 486 The instrument to do that is called a "condition variable", so called
457 because they represent a condition that must become true. 487 because they represent a condition that must become true.
458 488
489 Now is probably a good time to look at the examples further below.
490
459 Condition variables can be created by calling the "AnyEvent->condvar" 491 Condition variables can be created by calling the "AnyEvent->condvar"
460 method, usually without arguments. The only argument pair allowed is 492 method, usually without arguments. The only argument pair allowed is
461
462 "cb", which specifies a callback to be called when the condition 493 "cb", which specifies a callback to be called when the condition
463 variable becomes true, with the condition variable as the first argument 494 variable becomes true, with the condition variable as the first argument
464 (but not the results). 495 (but not the results).
465 496
466 After creation, the condition variable is "false" until it becomes 497 After creation, the condition variable is "false" until it becomes
… …
471 Condition variables are similar to callbacks, except that you can 502 Condition variables are similar to callbacks, except that you can
472 optionally wait for them. They can also be called merge points - points 503 optionally wait for them. They can also be called merge points - points
473 in time where multiple outstanding events have been processed. And yet 504 in time where multiple outstanding events have been processed. And yet
474 another way to call them is transactions - each condition variable can 505 another way to call them is transactions - each condition variable can
475 be used to represent a transaction, which finishes at some point and 506 be used to represent a transaction, which finishes at some point and
476 delivers a result. 507 delivers a result. And yet some people know them as "futures" - a
508 promise to compute/deliver something that you can wait for.
477 509
478 Condition variables are very useful to signal that something has 510 Condition variables are very useful to signal that something has
479 finished, for example, if you write a module that does asynchronous http 511 finished, for example, if you write a module that does asynchronous http
480 requests, then a condition variable would be the ideal candidate to 512 requests, then a condition variable would be the ideal candidate to
481 signal the availability of results. The user can either act when the 513 signal the availability of results. The user can either act when the
… …
515 after => 1, 547 after => 1,
516 cb => sub { $result_ready->send }, 548 cb => sub { $result_ready->send },
517 ); 549 );
518 550
519 # this "blocks" (while handling events) till the callback 551 # this "blocks" (while handling events) till the callback
520 # calls send 552 # calls -<send
521 $result_ready->recv; 553 $result_ready->recv;
522 554
523 Example: wait for a timer, but take advantage of the fact that condition 555 Example: wait for a timer, but take advantage of the fact that condition
524 variables are also code references. 556 variables are also callable directly.
525 557
526 my $done = AnyEvent->condvar; 558 my $done = AnyEvent->condvar;
527 my $delay = AnyEvent->timer (after => 5, cb => $done); 559 my $delay = AnyEvent->timer (after => 5, cb => $done);
528 $done->recv; 560 $done->recv;
529 561
… …
535 567
536 ... 568 ...
537 569
538 my @info = $couchdb->info->recv; 570 my @info = $couchdb->info->recv;
539 571
540 And this is how you would just ste a callback to be called whenever the 572 And this is how you would just set a callback to be called whenever the
541 results are available: 573 results are available:
542 574
543 $couchdb->info->cb (sub { 575 $couchdb->info->cb (sub {
544 my @info = $_[0]->recv; 576 my @info = $_[0]->recv;
545 }); 577 });
… …
560 592
561 Any arguments passed to the "send" call will be returned by all 593 Any arguments passed to the "send" call will be returned by all
562 future "->recv" calls. 594 future "->recv" calls.
563 595
564 Condition variables are overloaded so one can call them directly (as 596 Condition variables are overloaded so one can call them directly (as
565 a code reference). Calling them directly is the same as calling 597 if they were a code reference). Calling them directly is the same as
566 "send". Note, however, that many C-based event loops do not handle 598 calling "send".
567 overloading, so as tempting as it may be, passing a condition
568 variable instead of a callback does not work. Both the pure perl and
569 EV loops support overloading, however, as well as all functions that
570 use perl to invoke a callback (as in AnyEvent::Socket and
571 AnyEvent::DNS for example).
572 599
573 $cv->croak ($error) 600 $cv->croak ($error)
574 Similar to send, but causes all call's to "->recv" to invoke 601 Similar to send, but causes all call's to "->recv" to invoke
575 "Carp::croak" with the given error message/object/scalar. 602 "Carp::croak" with the given error message/object/scalar.
576 603
577 This can be used to signal any errors to the condition variable 604 This can be used to signal any errors to the condition variable
578 user/consumer. 605 user/consumer. Doing it this way instead of calling "croak" directly
606 delays the error detetcion, but has the overwhelmign advantage that
607 it diagnoses the error at the place where the result is expected,
608 and not deep in some event clalback without connection to the actual
609 code causing the problem.
579 610
580 $cv->begin ([group callback]) 611 $cv->begin ([group callback])
581 $cv->end 612 $cv->end
582 These two methods can be used to combine many transactions/events 613 These two methods can be used to combine many transactions/events
583 into one. For example, a function that pings many hosts in parallel 614 into one. For example, a function that pings many hosts in parallel
… …
671 function will call "croak". 702 function will call "croak".
672 703
673 In list context, all parameters passed to "send" will be returned, 704 In list context, all parameters passed to "send" will be returned,
674 in scalar context only the first one will be returned. 705 in scalar context only the first one will be returned.
675 706
707 Note that doing a blocking wait in a callback is not supported by
708 any event loop, that is, recursive invocation of a blocking "->recv"
709 is not allowed, and the "recv" call will "croak" if such a condition
710 is detected. This condition can be slightly loosened by using
711 Coro::AnyEvent, which allows you to do a blocking "->recv" from any
712 thread that doesn't run the event loop itself.
713
676 Not all event models support a blocking wait - some die in that case 714 Not all event models support a blocking wait - some die in that case
677 (programs might want to do that to stay interactive), so *if you are 715 (programs might want to do that to stay interactive), so *if you are
678 using this from a module, never require a blocking wait*, but let 716 using this from a module, never require a blocking wait*. Instead,
679 the caller decide whether the call will block or not (for example, 717 let the caller decide whether the call will block or not (for
680 by coupling condition variables with some kind of request results 718 example, by coupling condition variables with some kind of request
681 and supporting callbacks so the caller knows that getting the result 719 results and supporting callbacks so the caller knows that getting
682 will not block, while still supporting blocking waits if the caller 720 the result will not block, while still supporting blocking waits if
683 so desires). 721 the caller so desires).
684
685 Another reason *never* to "->recv" in a module is that you cannot
686 sensibly have two "->recv"'s in parallel, as that would require
687 multiple interpreters or coroutines/threads, none of which
688 "AnyEvent" can supply.
689
690 The Coro module, however, *can* and *does* supply coroutines and, in
691 fact, Coro::AnyEvent replaces AnyEvent's condvars by coroutine-safe
692 versions and also integrates coroutines into AnyEvent, making
693 blocking "->recv" calls perfectly safe as long as they are done from
694 another coroutine (one that doesn't run the event loop).
695 722
696 You can ensure that "-recv" never blocks by setting a callback and 723 You can ensure that "-recv" never blocks by setting a callback and
697 only calling "->recv" from within that callback (or at a later 724 only calling "->recv" from within that callback (or at a later
698 time). This will work even when the event loop does not support 725 time). This will work even when the event loop does not support
699 blocking waits otherwise. 726 blocking waits otherwise.
… …
709 The callback will be called when the condition becomes "true", i.e. 736 The callback will be called when the condition becomes "true", i.e.
710 when "send" or "croak" are called, with the only argument being the 737 when "send" or "croak" are called, with the only argument being the
711 condition variable itself. Calling "recv" inside the callback or at 738 condition variable itself. Calling "recv" inside the callback or at
712 any later time is guaranteed not to block. 739 any later time is guaranteed not to block.
713 740
741SUPPORTED EVENT LOOPS/BACKENDS
742 The available backend classes are (every class has its own manpage):
743
744 Backends that are autoprobed when no other event loop can be found.
745 EV is the preferred backend when no other event loop seems to be in
746 use. If EV is not installed, then AnyEvent will try Event, and,
747 failing that, will fall back to its own pure-perl implementation,
748 which is available everywhere as it comes with AnyEvent itself.
749
750 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
751 AnyEvent::Impl::Event based on Event, very stable, few glitches.
752 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
753
754 Backends that are transparently being picked up when they are used.
755 These will be used when they are currently loaded when the first
756 watcher is created, in which case it is assumed that the application
757 is using them. This means that AnyEvent will automatically pick the
758 right backend when the main program loads an event module before
759 anything starts to create watchers. Nothing special needs to be done
760 by the main program.
761
762 AnyEvent::Impl::Glib based on Glib, slow but very stable.
763 AnyEvent::Impl::Tk based on Tk, very broken.
764 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
765 AnyEvent::Impl::POE based on POE, very slow, some limitations.
766 AnyEvent::Impl::Irssi used when running within irssi.
767
768 Backends with special needs.
769 Qt requires the Qt::Application to be instantiated first, but will
770 otherwise be picked up automatically. As long as the main program
771 instantiates the application before any AnyEvent watchers are
772 created, everything should just work.
773
774 AnyEvent::Impl::Qt based on Qt.
775
776 Support for IO::Async can only be partial, as it is too broken and
777 architecturally limited to even support the AnyEvent API. It also is
778 the only event loop that needs the loop to be set explicitly, so it
779 can only be used by a main program knowing about AnyEvent. See
780 AnyEvent::Impl::Async for the gory details.
781
782 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed.
783
784 Event loops that are indirectly supported via other backends.
785 Some event loops can be supported via other modules:
786
787 There is no direct support for WxWidgets (Wx) or Prima.
788
789 WxWidgets has no support for watching file handles. However, you can
790 use WxWidgets through the POE adaptor, as POE has a Wx backend that
791 simply polls 20 times per second, which was considered to be too
792 horrible to even consider for AnyEvent.
793
794 Prima is not supported as nobody seems to be using it, but it has a
795 POE backend, so it can be supported through POE.
796
797 AnyEvent knows about both Prima and Wx, however, and will try to
798 load POE when detecting them, in the hope that POE will pick them
799 up, in which case everything will be automatic.
800
714GLOBAL VARIABLES AND FUNCTIONS 801GLOBAL VARIABLES AND FUNCTIONS
802 These are not normally required to use AnyEvent, but can be useful to
803 write AnyEvent extension modules.
804
715 $AnyEvent::MODEL 805 $AnyEvent::MODEL
716 Contains "undef" until the first watcher is being created. Then it 806 Contains "undef" until the first watcher is being created, before
807 the backend has been autodetected.
808
717 contains the event model that is being used, which is the name of 809 Afterwards it contains the event model that is being used, which is
718 the Perl class implementing the model. This class is usually one of 810 the name of the Perl class implementing the model. This class is
719 the "AnyEvent::Impl:xxx" modules, but can be any other class in the 811 usually one of the "AnyEvent::Impl:xxx" modules, but can be any
720 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). 812 other class in the case AnyEvent has been extended at runtime (e.g.
721 813 in *rxvt-unicode* it will be "urxvt::anyevent").
722 The known classes so far are:
723
724 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
725 AnyEvent::Impl::Event based on Event, second best choice.
726 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
727 AnyEvent::Impl::Glib based on Glib, third-best choice.
728 AnyEvent::Impl::Tk based on Tk, very bad choice.
729 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
730 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
731 AnyEvent::Impl::POE based on POE, not generic enough for full support.
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
737 There is no support for WxWidgets, as WxWidgets has no support for
738 watching file handles. However, you can use WxWidgets through the
739 POE Adaptor, as POE has a Wx backend that simply polls 20 times per
740 second, which was considered to be too horrible to even consider for
741 AnyEvent. Likewise, other POE backends can be used by AnyEvent by
742 using it's adaptor.
743
744 AnyEvent knows about Prima and Wx and will try to use POE when
745 autodetecting them.
746 814
747 AnyEvent::detect 815 AnyEvent::detect
748 Returns $AnyEvent::MODEL, forcing autodetection of the event model 816 Returns $AnyEvent::MODEL, forcing autodetection of the event model
749 if necessary. You should only call this function right before you 817 if necessary. You should only call this function right before you
750 would have created an AnyEvent watcher anyway, that is, as late as 818 would have created an AnyEvent watcher anyway, that is, as late as
751 possible at runtime. 819 possible at runtime, and not e.g. while initialising of your module.
820
821 If you need to do some initialisation before AnyEvent watchers are
822 created, use "post_detect".
752 823
753 $guard = AnyEvent::post_detect { BLOCK } 824 $guard = AnyEvent::post_detect { BLOCK }
754 Arranges for the code block to be executed as soon as the event 825 Arranges for the code block to be executed as soon as the event
755 model is autodetected (or immediately if this has already happened). 826 model is autodetected (or immediately if this has already happened).
756 827
828 The block will be executed *after* the actual backend has been
829 detected ($AnyEvent::MODEL is set), but *before* any watchers have
830 been created, so it is possible to e.g. patch @AnyEvent::ISA or do
831 other initialisations - see the sources of AnyEvent::Strict or
832 AnyEvent::AIO to see how this is used.
833
834 The most common usage is to create some global watchers, without
835 forcing event module detection too early, for example, AnyEvent::AIO
836 creates and installs the global IO::AIO watcher in a "post_detect"
837 block to avoid autodetecting the event module at load time.
838
757 If called in scalar or list context, then it creates and returns an 839 If called in scalar or list context, then it creates and returns an
758 object that automatically removes the callback again when it is 840 object that automatically removes the callback again when it is
841 destroyed (or "undef" when the hook was immediately executed). See
759 destroyed. See Coro::BDB for a case where this is useful. 842 AnyEvent::AIO for a case where this is useful.
843
844 Example: Create a watcher for the IO::AIO module and store it in
845 $WATCHER. Only do so after the event loop is initialised, though.
846
847 our WATCHER;
848
849 my $guard = AnyEvent::post_detect {
850 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
851 };
852
853 # the ||= is important in case post_detect immediately runs the block,
854 # as to not clobber the newly-created watcher. assigning both watcher and
855 # post_detect guard to the same variable has the advantage of users being
856 # able to just C<undef $WATCHER> if the watcher causes them grief.
857
858 $WATCHER ||= $guard;
760 859
761 @AnyEvent::post_detect 860 @AnyEvent::post_detect
762 If there are any code references in this array (you can "push" to it 861 If there are any code references in this array (you can "push" to it
763 before or after loading AnyEvent), then they will called directly 862 before or after loading AnyEvent), then they will called directly
764 after the event loop has been chosen. 863 after the event loop has been chosen.
765 864
766 You should check $AnyEvent::MODEL before adding to this array, 865 You should check $AnyEvent::MODEL before adding to this array,
767 though: if it contains a true value then the event loop has already 866 though: if it is defined then the event loop has already been
768 been detected, and the array will be ignored. 867 detected, and the array will be ignored.
769 868
770 Best use "AnyEvent::post_detect { BLOCK }" instead. 869 Best use "AnyEvent::post_detect { BLOCK }" when your application
870 allows it,as it takes care of these details.
871
872 This variable is mainly useful for modules that can do something
873 useful when AnyEvent is used and thus want to know when it is
874 initialised, but do not need to even load it by default. This array
875 provides the means to hook into AnyEvent passively, without loading
876 it.
771 877
772WHAT TO DO IN A MODULE 878WHAT TO DO IN A MODULE
773 As a module author, you should "use AnyEvent" and call AnyEvent methods 879 As a module author, you should "use AnyEvent" and call AnyEvent methods
774 freely, but you should not load a specific event module or rely on it. 880 freely, but you should not load a specific event module or rely on it.
775 881
… …
826 variable somewhere, waiting for it, and sending it when the program 932 variable somewhere, waiting for it, and sending it when the program
827 should exit cleanly. 933 should exit cleanly.
828 934
829OTHER MODULES 935OTHER MODULES
830 The following is a non-exhaustive list of additional modules that use 936 The following is a non-exhaustive list of additional modules that use
831 AnyEvent and can therefore be mixed easily with other AnyEvent modules 937 AnyEvent as a client and can therefore be mixed easily with other
832 in the same program. Some of the modules come with AnyEvent, some are 938 AnyEvent modules and other event loops in the same program. Some of the
833 available via CPAN. 939 modules come with AnyEvent, most are available via CPAN.
834 940
835 AnyEvent::Util 941 AnyEvent::Util
836 Contains various utility functions that replace often-used but 942 Contains various utility functions that replace often-used but
837 blocking functions such as "inet_aton" by event-/callback-based 943 blocking functions such as "inet_aton" by event-/callback-based
838 versions. 944 versions.
… …
844 more. 950 more.
845 951
846 AnyEvent::Handle 952 AnyEvent::Handle
847 Provide read and write buffers, manages watchers for reads and 953 Provide read and write buffers, manages watchers for reads and
848 writes, supports raw and formatted I/O, I/O queued and fully 954 writes, supports raw and formatted I/O, I/O queued and fully
849 transparent and non-blocking SSL/TLS. 955 transparent and non-blocking SSL/TLS (via AnyEvent::TLS.
850 956
851 AnyEvent::DNS 957 AnyEvent::DNS
852 Provides rich asynchronous DNS resolver capabilities. 958 Provides rich asynchronous DNS resolver capabilities.
853 959
854 AnyEvent::HTTP 960 AnyEvent::HTTP
… …
875 981
876 AnyEvent::GPSD 982 AnyEvent::GPSD
877 A non-blocking interface to gpsd, a daemon delivering GPS 983 A non-blocking interface to gpsd, a daemon delivering GPS
878 information. 984 information.
879 985
986 AnyEvent::IRC
987 AnyEvent based IRC client module family (replacing the older
988 Net::IRC3).
989
990 AnyEvent::XMPP
991 AnyEvent based XMPP (Jabber protocol) module family (replacing the
992 older Net::XMPP2>.
993
880 AnyEvent::IGS 994 AnyEvent::IGS
881 A non-blocking interface to the Internet Go Server protocol (used by 995 A non-blocking interface to the Internet Go Server protocol (used by
882 App::IGS). 996 App::IGS).
883 997
884 AnyEvent::IRC
885 AnyEvent based IRC client module family (replacing the older
886 Net::IRC3).
887
888 Net::XMPP2
889 AnyEvent based XMPP (Jabber protocol) module family.
890
891 Net::FCP 998 Net::FCP
892 AnyEvent-based implementation of the Freenet Client Protocol, 999 AnyEvent-based implementation of the Freenet Client Protocol,
893 birthplace of AnyEvent. 1000 birthplace of AnyEvent.
894 1001
895 Event::ExecFlow 1002 Event::ExecFlow
896 High level API for event-based execution flow control. 1003 High level API for event-based execution flow control.
897 1004
898 Coro 1005 Coro
899 Has special support for AnyEvent via Coro::AnyEvent. 1006 Has special support for AnyEvent via Coro::AnyEvent.
900
901 IO::Lambda
902 The lambda approach to I/O - don't ask, look there. Can use
903 AnyEvent.
904 1007
905ERROR AND EXCEPTION HANDLING 1008ERROR AND EXCEPTION HANDLING
906 In general, AnyEvent does not do any error handling - it relies on the 1009 In general, AnyEvent does not do any error handling - it relies on the
907 caller to do that if required. The AnyEvent::Strict module (see also the 1010 caller to do that if required. The AnyEvent::Strict module (see also the
908 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict 1011 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
… …
936 by "PERL_ANYEVENT_MODEL". 1039 by "PERL_ANYEVENT_MODEL".
937 1040
938 When set to 2 or higher, cause AnyEvent to report to STDERR which 1041 When set to 2 or higher, cause AnyEvent to report to STDERR which
939 event model it chooses. 1042 event model it chooses.
940 1043
1044 When set to 8 or higher, then AnyEvent will report extra information
1045 on which optional modules it loads and how it implements certain
1046 features.
1047
941 "PERL_ANYEVENT_STRICT" 1048 "PERL_ANYEVENT_STRICT"
942 AnyEvent does not do much argument checking by default, as thorough 1049 AnyEvent does not do much argument checking by default, as thorough
943 argument checking is very costly. Setting this variable to a true 1050 argument checking is very costly. Setting this variable to a true
944 value will cause AnyEvent to load "AnyEvent::Strict" and then to 1051 value will cause AnyEvent to load "AnyEvent::Strict" and then to
945 thoroughly check the arguments passed to most method calls. If it 1052 thoroughly check the arguments passed to most method calls. If it
946 finds any problems, it will croak. 1053 finds any problems, it will croak.
947 1054
948 In other words, enables "strict" mode. 1055 In other words, enables "strict" mode.
949 1056
950 Unlike "use strict", it is definitely recommended to keep it off in 1057 Unlike "use strict" (or it's modern cousin, "use common::sense", it
951 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment 1058 is definitely recommended to keep it off in production. Keeping
1059 "PERL_ANYEVENT_STRICT=1" in your environment while developing
952 while developing programs can be very useful, however. 1060 programs can be very useful, however.
953 1061
954 "PERL_ANYEVENT_MODEL" 1062 "PERL_ANYEVENT_MODEL"
955 This can be used to specify the event model to be used by AnyEvent, 1063 This can be used to specify the event model to be used by AnyEvent,
956 before auto detection and -probing kicks in. It must be a string 1064 before auto detection and -probing kicks in. It must be a string
957 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 1065 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
998 EDNS0 in its DNS requests. 1106 EDNS0 in its DNS requests.
999 1107
1000 "PERL_ANYEVENT_MAX_FORKS" 1108 "PERL_ANYEVENT_MAX_FORKS"
1001 The maximum number of child processes that 1109 The maximum number of child processes that
1002 "AnyEvent::Util::fork_call" will create in parallel. 1110 "AnyEvent::Util::fork_call" will create in parallel.
1111
1112 "PERL_ANYEVENT_MAX_OUTSTANDING_DNS"
1113 The default value for the "max_outstanding" parameter for the
1114 default DNS resolver - this is the maximum number of parallel DNS
1115 requests that are sent to the DNS server.
1116
1117 "PERL_ANYEVENT_RESOLV_CONF"
1118 The file to use instead of /etc/resolv.conf (or OS-specific
1119 configuration) in the default resolver. When set to the empty
1120 string, no default config will be used.
1121
1122 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH".
1123 When neither "ca_file" nor "ca_path" was specified during
1124 AnyEvent::TLS context creation, and either of these environment
1125 variables exist, they will be used to specify CA certificate
1126 locations instead of a system-dependent default.
1127
1128 "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT"
1129 When these are set to 1, then the respective modules are not loaded.
1130 Mostly good for testing AnyEvent itself.
1003 1131
1004SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1132SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1005 This is an advanced topic that you do not normally need to use AnyEvent 1133 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 1134 in a module. This section is only of use to event loop authors who want
1007 to provide AnyEvent compatibility. 1135 to provide AnyEvent compatibility.
… …
1512 SIGCHLD 1640 SIGCHLD
1513 A handler for "SIGCHLD" is installed by AnyEvent's child watcher 1641 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1514 emulation for event loops that do not support them natively. Also, 1642 emulation for event loops that do not support them natively. Also,
1515 some event loops install a similar handler. 1643 some event loops install a similar handler.
1516 1644
1517 If, when AnyEvent is loaded, SIGCHLD is set to IGNORE, then AnyEvent 1645 Additionally, when AnyEvent is loaded and SIGCHLD is set to IGNORE,
1518 will reset it to default, to avoid losing child exit statuses. 1646 then AnyEvent will reset it to default, to avoid losing child exit
1647 statuses.
1519 1648
1520 SIGPIPE 1649 SIGPIPE
1521 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is 1650 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1522 "undef" when AnyEvent gets loaded. 1651 "undef" when AnyEvent gets loaded.
1523 1652
… …
1531 it is that this way, the handler will be restored to defaults on 1660 it is that this way, the handler will be restored to defaults on
1532 exec. 1661 exec.
1533 1662
1534 Feel free to install your own handler, or reset it to defaults. 1663 Feel free to install your own handler, or reset it to defaults.
1535 1664
1665RECOMMENDED/OPTIONAL MODULES
1666 One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
1667 it's built-in modules) are required to use it.
1668
1669 That does not mean that AnyEvent won't take advantage of some additional
1670 modules if they are installed.
1671
1672 This section epxlains which additional modules will be used, and how
1673 they affect AnyEvent's operetion.
1674
1675 Async::Interrupt
1676 This slightly arcane module is used to implement fast signal
1677 handling: To my knowledge, there is no way to do completely
1678 race-free and quick signal handling in pure perl. To ensure that
1679 signals still get delivered, AnyEvent will start an interval timer
1680 to wake up perl (and catch the signals) with some delay (default is
1681 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY).
1682
1683 If this module is available, then it will be used to implement
1684 signal catching, which means that signals will not be delayed, and
1685 the event loop will not be interrupted regularly, which is more
1686 efficient (And good for battery life on laptops).
1687
1688 This affects not just the pure-perl event loop, but also other event
1689 loops that have no signal handling on their own (e.g. Glib, Tk, Qt).
1690
1691 Some event loops (POE, Event, Event::Lib) offer signal watchers
1692 natively, and either employ their own workarounds (POE) or use
1693 AnyEvent's workaround (using $AnyEvent::MAX_SIGNAL_LATENCY).
1694 Installing Async::Interrupt does nothing for those backends.
1695
1696 EV This module isn't really "optional", as it is simply one of the
1697 backend event loops that AnyEvent can use. However, it is simply the
1698 best event loop available in terms of features, speed and stability:
1699 It supports the AnyEvent API optimally, implements all the watcher
1700 types in XS, does automatic timer adjustments even when no monotonic
1701 clock is available, can take avdantage of advanced kernel interfaces
1702 such as "epoll" and "kqueue", and is the fastest backend *by far*.
1703 You can even embed Glib/Gtk2 in it (or vice versa, see EV::Glib and
1704 Glib::EV).
1705
1706 Guard
1707 The guard module, when used, will be used to implement
1708 "AnyEvent::Util::guard". This speeds up guards considerably (and
1709 uses a lot less memory), but otherwise doesn't affect guard
1710 operation much. It is purely used for performance.
1711
1712 JSON and JSON::XS
1713 This module is required when you want to read or write JSON data via
1714 AnyEvent::Handle. It is also written in pure-perl, but can take
1715 advantage of the ultra-high-speed JSON::XS module when it is
1716 installed.
1717
1718 In fact, AnyEvent::Handle will use JSON::XS by default if it is
1719 installed.
1720
1721 Net::SSLeay
1722 Implementing TLS/SSL in Perl is certainly interesting, but not very
1723 worthwhile: If this module is installed, then AnyEvent::Handle (with
1724 the help of AnyEvent::TLS), gains the ability to do TLS/SSL.
1725
1726 Time::HiRes
1727 This module is part of perl since release 5.008. It will be used
1728 when the chosen event library does not come with a timing source on
1729 it's own. The pure-perl event loop (AnyEvent::Impl::Perl) will
1730 additionally use it to try to use a monotonic clock for timing
1731 stability.
1732
1536FORK 1733FORK
1537 Most event libraries are not fork-safe. The ones who are usually are 1734 Most event libraries are not fork-safe. The ones who are usually are
1538 because they rely on inefficient but fork-safe "select" or "poll" calls. 1735 because they rely on inefficient but fork-safe "select" or "poll" calls.
1539 Only EV is fully fork-aware. 1736 Only EV is fully fork-aware.
1540 1737
1541 If you have to fork, you must either do so *before* creating your first 1738 If you have to fork, you must either do so *before* creating your first
1542 watcher OR you must not use AnyEvent at all in the child. 1739 watcher OR you must not use AnyEvent at all in the child OR you must do
1740 something completely out of the scope of AnyEvent.
1543 1741
1544SECURITY CONSIDERATIONS 1742SECURITY CONSIDERATIONS
1545 AnyEvent can be forced to load any event model via 1743 AnyEvent can be forced to load any event model via
1546 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used 1744 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
1547 to execute arbitrary code or directly gain access, it can easily be used 1745 to execute arbitrary code or directly gain access, it can easily be used
… …
1578 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, 1776 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
1579 Event::Lib, Qt, POE. 1777 Event::Lib, Qt, POE.
1580 1778
1581 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, 1779 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1582 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, 1780 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1583 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE. 1781 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
1782 AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi.
1584 1783
1585 Non-blocking file handles, sockets, TCP clients and servers: 1784 Non-blocking file handles, sockets, TCP clients and servers:
1586 AnyEvent::Handle, AnyEvent::Socket. 1785 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1587 1786
1588 Asynchronous DNS: AnyEvent::DNS. 1787 Asynchronous DNS: AnyEvent::DNS.
1589 1788
1590 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, 1789 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1591 1790
1592 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS. 1791 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::XMPP,
1792 AnyEvent::HTTP.
1593 1793
1594AUTHOR 1794AUTHOR
1595 Marc Lehmann <schmorp@schmorp.de> 1795 Marc Lehmann <schmorp@schmorp.de>
1596 http://home.schmorp.de/ 1796 http://home.schmorp.de/
1597 1797

Diff Legend

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