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

Comparing AnyEvent/README (file contents):
Revision 1.29 by root, Tue Jul 29 10:20:33 2008 UTC vs.
Revision 1.35 by root, Wed Mar 25 17:33:11 2009 UTC

… …
330 330
331 CHILD PROCESS WATCHERS 331 CHILD PROCESS WATCHERS
332 You can also watch on a child process exit and catch its exit status. 332 You can also watch on a child process exit and catch its exit status.
333 333
334 The child process is specified by the "pid" argument (if set to 0, it 334 The child process is specified by the "pid" argument (if set to 0, it
335 watches for any child process exit). The watcher will trigger as often 335 watches for any child process exit). The watcher will triggered only
336 as status change for the child are received. This works by installing a 336 when the child process has finished and an exit status is available, not
337 signal handler for "SIGCHLD". The callback will be called with the pid 337 on any trace events (stopped/continued).
338 and exit status (as returned by waitpid), so unlike other watcher types, 338
339 you *can* rely on child watcher callback arguments. 339 The callback will be called with the pid and exit status (as returned by
340 waitpid), so unlike other watcher types, you *can* rely on child watcher
341 callback arguments.
342
343 This watcher type works by installing a signal handler for "SIGCHLD",
344 and since it cannot be shared, nothing else should use SIGCHLD or reap
345 random child processes (waiting for specific child processes, e.g.
346 inside "system", is just fine).
340 347
341 There is a slight catch to child watchers, however: you usually start 348 There is a slight catch to child watchers, however: you usually start
342 them *after* the child process was created, and this means the process 349 them *after* the child process was created, and this means the process
343 could have exited already (and no SIGCHLD will be sent anymore). 350 could have exited already (and no SIGCHLD will be sent anymore).
344 351
… …
770 777
771 AnyEvent::IGS 778 AnyEvent::IGS
772 A non-blocking interface to the Internet Go Server protocol (used by 779 A non-blocking interface to the Internet Go Server protocol (used by
773 App::IGS). 780 App::IGS).
774 781
782 AnyEvent::IRC
783 AnyEvent based IRC client module family (replacing the older
775 Net::IRC3 784 Net::IRC3).
776 AnyEvent based IRC client module family.
777 785
778 Net::XMPP2 786 Net::XMPP2
779 AnyEvent based XMPP (Jabber protocol) module family. 787 AnyEvent based XMPP (Jabber protocol) module family.
780 788
781 Net::FCP 789 Net::FCP
… …
790 798
791 IO::Lambda 799 IO::Lambda
792 The lambda approach to I/O - don't ask, look there. Can use 800 The lambda approach to I/O - don't ask, look there. Can use
793 AnyEvent. 801 AnyEvent.
794 802
795SUPPLYING YOUR OWN EVENT MODEL INTERFACE 803ERROR AND EXCEPTION HANDLING
796 This is an advanced topic that you do not normally need to use AnyEvent 804 In general, AnyEvent does not do any error handling - it relies on the
797 in a module. This section is only of use to event loop authors who want 805 caller to do that if required. The AnyEvent::Strict module (see also the
798 to provide AnyEvent compatibility. 806 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
807 checking of all AnyEvent methods, however, which is highly useful during
808 development.
799 809
800 If you need to support another event library which isn't directly 810 As for exception handling (i.e. runtime errors and exceptions thrown
801 supported by AnyEvent, you can supply your own interface to it by 811 while executing a callback), this is not only highly event-loop
802 pushing, before the first watcher gets created, the package name of the 812 specific, but also not in any way wrapped by this module, as this is the
803 event module and the package name of the interface to use onto 813 job of the main program.
804 @AnyEvent::REGISTRY. You can do that before and even without loading
805 AnyEvent, so it is reasonably cheap.
806 814
807 Example: 815 The pure perl event loop simply re-throws the exception (usually within
808 816 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
809 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 817 Glib uses "install_exception_handler" and so on.
810
811 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
812 package/class when it finds the "urxvt" package/module is already
813 loaded.
814
815 When AnyEvent is loaded and asked to find a suitable event model, it
816 will first check for the presence of urxvt by trying to "use" the
817 "urxvt::anyevent" module.
818
819 The class should provide implementations for all watcher types. See
820 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
821 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
822 the sources.
823
824 If you don't provide "signal" and "child" watchers than AnyEvent will
825 provide suitable (hopefully) replacements.
826
827 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
828 terminal emulator uses the above line as-is. An interface isn't included
829 in AnyEvent because it doesn't make sense outside the embedded
830 interpreter inside *rxvt-unicode*, and it is updated and maintained as
831 part of the *rxvt-unicode* distribution.
832
833 *rxvt-unicode* also cheats a bit by not providing blocking access to
834 condition variables: code blocking while waiting for a condition will
835 "die". This still works with most modules/usages, and blocking calls
836 must not be done in an interactive application, so it makes sense.
837 818
838ENVIRONMENT VARIABLES 819ENVIRONMENT VARIABLES
839 The following environment variables are used by this module: 820 The following environment variables are used by this module or its
821 submodules:
840 822
841 "PERL_ANYEVENT_VERBOSE" 823 "PERL_ANYEVENT_VERBOSE"
842 By default, AnyEvent will be completely silent except in fatal 824 By default, AnyEvent will be completely silent except in fatal
843 conditions. You can set this environment variable to make AnyEvent 825 conditions. You can set this environment variable to make AnyEvent
844 more talkative. 826 more talkative.
… …
857 thoroughly check the arguments passed to most method calls. If it 839 thoroughly check the arguments passed to most method calls. If it
858 finds any problems it will croak. 840 finds any problems it will croak.
859 841
860 In other words, enables "strict" mode. 842 In other words, enables "strict" mode.
861 843
862 Unlike "use strict" it is definitely recommended ot keep it off in 844 Unlike "use strict", it is definitely recommended ot keep it off in
863 production. 845 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment
846 while developing programs can be very useful, however.
864 847
865 "PERL_ANYEVENT_MODEL" 848 "PERL_ANYEVENT_MODEL"
866 This can be used to specify the event model to be used by AnyEvent, 849 This can be used to specify the event model to be used by AnyEvent,
867 before auto detection and -probing kicks in. It must be a string 850 before auto detection and -probing kicks in. It must be a string
868 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 851 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
887 mentioned will be used, and preference will be given to protocols 870 mentioned will be used, and preference will be given to protocols
888 mentioned earlier in the list. 871 mentioned earlier in the list.
889 872
890 This variable can effectively be used for denial-of-service attacks 873 This variable can effectively be used for denial-of-service attacks
891 against local programs (e.g. when setuid), although the impact is 874 against local programs (e.g. when setuid), although the impact is
892 likely small, as the program has to handle connection errors 875 likely small, as the program has to handle conenction and other
893 already- 876 failures anyways.
894 877
895 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over 878 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
896 IPv6, but support both and try to use both. 879 IPv6, but support both and try to use both.
897 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to 880 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
898 resolve or contact IPv6 addresses. 881 resolve or contact IPv6 addresses.
… …
909 EDNS0 in its DNS requests. 892 EDNS0 in its DNS requests.
910 893
911 "PERL_ANYEVENT_MAX_FORKS" 894 "PERL_ANYEVENT_MAX_FORKS"
912 The maximum number of child processes that 895 The maximum number of child processes that
913 "AnyEvent::Util::fork_call" will create in parallel. 896 "AnyEvent::Util::fork_call" will create in parallel.
897
898SUPPLYING YOUR OWN EVENT MODEL INTERFACE
899 This is an advanced topic that you do not normally need to use AnyEvent
900 in a module. This section is only of use to event loop authors who want
901 to provide AnyEvent compatibility.
902
903 If you need to support another event library which isn't directly
904 supported by AnyEvent, you can supply your own interface to it by
905 pushing, before the first watcher gets created, the package name of the
906 event module and the package name of the interface to use onto
907 @AnyEvent::REGISTRY. You can do that before and even without loading
908 AnyEvent, so it is reasonably cheap.
909
910 Example:
911
912 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
913
914 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
915 package/class when it finds the "urxvt" package/module is already
916 loaded.
917
918 When AnyEvent is loaded and asked to find a suitable event model, it
919 will first check for the presence of urxvt by trying to "use" the
920 "urxvt::anyevent" module.
921
922 The class should provide implementations for all watcher types. See
923 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
924 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
925 the sources.
926
927 If you don't provide "signal" and "child" watchers than AnyEvent will
928 provide suitable (hopefully) replacements.
929
930 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
931 terminal emulator uses the above line as-is. An interface isn't included
932 in AnyEvent because it doesn't make sense outside the embedded
933 interpreter inside *rxvt-unicode*, and it is updated and maintained as
934 part of the *rxvt-unicode* distribution.
935
936 *rxvt-unicode* also cheats a bit by not providing blocking access to
937 condition variables: code blocking while waiting for a condition will
938 "die". This still works with most modules/usages, and blocking calls
939 must not be done in an interactive application, so it makes sense.
914 940
915EXAMPLE PROGRAM 941EXAMPLE PROGRAM
916 The following program uses an I/O watcher to read data from STDIN, a 942 The following program uses an I/O watcher to read data from STDIN, a
917 timer to display a message once per second, and a condition variable to 943 timer to display a message once per second, and a condition variable to
918 quit the program when the user enters quit: 944 quit the program when the user enters quit:
… …
1105 *destroy* is the time, in microseconds, that it takes to destroy a 1131 *destroy* is the time, in microseconds, that it takes to destroy a
1106 single watcher. 1132 single watcher.
1107 1133
1108 Results 1134 Results
1109 name watchers bytes create invoke destroy comment 1135 name watchers bytes create invoke destroy comment
1110 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1136 EV/EV 400000 224 0.47 0.35 0.27 EV native interface
1111 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers 1137 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
1112 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal 1138 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
1113 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation 1139 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
1114 Event/Event 16000 516 31.88 31.30 0.85 Event native interface 1140 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
1115 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers 1141 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
1116 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour 1142 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
1117 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers 1143 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
1118 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event 1144 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
1119 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select 1145 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
1120 1146
1121 Discussion 1147 Discussion
1122 The benchmark does *not* measure scalability of the event loop very 1148 The benchmark does *not* measure scalability of the event loop very
1123 well. For example, a select-based event loop (such as the pure perl one) 1149 well. For example, a select-based event loop (such as the pure perl one)
1124 can never compete with an event loop that uses epoll when the number of 1150 can never compete with an event loop that uses epoll when the number of
… …
1305 1331
1306 Summary 1332 Summary
1307 * C-based event loops perform very well with small number of watchers, 1333 * C-based event loops perform very well with small number of watchers,
1308 as the management overhead dominates. 1334 as the management overhead dominates.
1309 1335
1336SIGNALS
1337 AnyEvent currently installs handlers for these signals:
1338
1339 SIGCHLD
1340 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1341 emulation for event loops that do not support them natively. Also,
1342 some event loops install a similar handler.
1343
1344 SIGPIPE
1345 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1346 "undef" when AnyEvent gets loaded.
1347
1348 The rationale for this is that AnyEvent users usually do not really
1349 depend on SIGPIPE delivery (which is purely an optimisation for
1350 shell use, or badly-written programs), but "SIGPIPE" can cause
1351 spurious and rare program exits as a lot of people do not expect
1352 "SIGPIPE" when writing to some random socket.
1353
1354 The rationale for installing a no-op handler as opposed to ignoring
1355 it is that this way, the handler will be restored to defaults on
1356 exec.
1357
1358 Feel free to install your own handler, or reset it to defaults.
1359
1310FORK 1360FORK
1311 Most event libraries are not fork-safe. The ones who are usually are 1361 Most event libraries are not fork-safe. The ones who are usually are
1312 because they rely on inefficient but fork-safe "select" or "poll" calls. 1362 because they rely on inefficient but fork-safe "select" or "poll" calls.
1313 Only EV is fully fork-aware. 1363 Only EV is fully fork-aware.
1314 1364

Diff Legend

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