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.37 by root, Mon Apr 20 14:34:18 2009 UTC

… …
132 These watchers are normal Perl objects with normal Perl lifetime. After 132 These watchers are normal Perl objects with normal Perl lifetime. After
133 creating a watcher it will immediately "watch" for events and invoke the 133 creating a watcher it will immediately "watch" for events and invoke the
134 callback when the event occurs (of course, only when the event model is 134 callback when the event occurs (of course, only when the event model is
135 in control). 135 in control).
136 136
137 Note that callbacks must not permanently change global variables
138 potentially in use by the event loop (such as $_ or $[) and that
139 callbacks must not "die". The former is good programming practise in
140 Perl and the latter stems from the fact that exception handling differs
141 widely between event loops.
142
137 To disable the watcher you have to destroy it (e.g. by setting the 143 To disable the watcher you have to destroy it (e.g. by setting the
138 variable you store it in to "undef" or otherwise deleting all references 144 variable you store it in to "undef" or otherwise deleting all references
139 to it). 145 to it).
140 146
141 All watchers are created by calling a method on the "AnyEvent" class. 147 All watchers are created by calling a method on the "AnyEvent" class.
… …
156 162
157 I/O WATCHERS 163 I/O WATCHERS
158 You can create an I/O watcher by calling the "AnyEvent->io" method with 164 You can create an I/O watcher by calling the "AnyEvent->io" method with
159 the following mandatory key-value pairs as arguments: 165 the following mandatory key-value pairs as arguments:
160 166
161 "fh" the Perl *file handle* (*not* file descriptor) to watch for events 167 "fh" is the Perl *file handle* (*not* file descriptor) to watch for
162 (AnyEvent might or might not keep a reference to this file handle). 168 events (AnyEvent might or might not keep a reference to this file
169 handle). Note that only file handles pointing to things for which
170 non-blocking operation makes sense are allowed. This includes sockets,
171 most character devices, pipes, fifos and so on, but not for example
172 files or block devices.
173
163 "poll" must be a string that is either "r" or "w", which creates a 174 "poll" must be a string that is either "r" or "w", which creates a
164 watcher waiting for "r"eadable or "w"ritable events, respectively. "cb" 175 watcher waiting for "r"eadable or "w"ritable events, respectively.
176
165 is the callback to invoke each time the file handle becomes ready. 177 "cb" is the callback to invoke each time the file handle becomes ready.
166 178
167 Although the callback might get passed parameters, their value and 179 Although the callback might get passed parameters, their value and
168 presence is undefined and you cannot rely on them. Portable AnyEvent 180 presence is undefined and you cannot rely on them. Portable AnyEvent
169 callbacks cannot use arguments passed to I/O watcher callbacks. 181 callbacks cannot use arguments passed to I/O watcher callbacks.
170 182
… …
302 In either case, if you care (and in most cases, you don't), then you 314 In either case, if you care (and in most cases, you don't), then you
303 can get whatever behaviour you want with any event loop, by taking 315 can get whatever behaviour you want with any event loop, by taking
304 the difference between "AnyEvent->time" and "AnyEvent->now" into 316 the difference between "AnyEvent->time" and "AnyEvent->now" into
305 account. 317 account.
306 318
319 AnyEvent->now_update
320 Some event loops (such as EV or AnyEvent::Impl::Perl) cache the
321 current time for each loop iteration (see the discussion of
322 AnyEvent->now, above).
323
324 When a callback runs for a long time (or when the process sleeps),
325 then this "current" time will differ substantially from the real
326 time, which might affect timers and time-outs.
327
328 When this is the case, you can call this method, which will update
329 the event loop's idea of "current time".
330
331 Note that updating the time *might* cause some events to be handled.
332
307 SIGNAL WATCHERS 333 SIGNAL WATCHERS
308 You can watch for signals using a signal watcher, "signal" is the signal 334 You can watch for signals using a signal watcher, "signal" is the signal
309 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl 335 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl
310 callback to be invoked whenever a signal occurs. 336 callback to be invoked whenever a signal occurs.
311 337
… …
330 356
331 CHILD PROCESS WATCHERS 357 CHILD PROCESS WATCHERS
332 You can also watch on a child process exit and catch its exit status. 358 You can also watch on a child process exit and catch its exit status.
333 359
334 The child process is specified by the "pid" argument (if set to 0, it 360 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 361 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 362 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 363 on any trace events (stopped/continued).
338 and exit status (as returned by waitpid), so unlike other watcher types, 364
339 you *can* rely on child watcher callback arguments. 365 The callback will be called with the pid and exit status (as returned by
366 waitpid), so unlike other watcher types, you *can* rely on child watcher
367 callback arguments.
368
369 This watcher type works by installing a signal handler for "SIGCHLD",
370 and since it cannot be shared, nothing else should use SIGCHLD or reap
371 random child processes (waiting for specific child processes, e.g.
372 inside "system", is just fine).
340 373
341 There is a slight catch to child watchers, however: you usually start 374 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 375 them *after* the child process was created, and this means the process
343 could have exited already (and no SIGCHLD will be sent anymore). 376 could have exited already (and no SIGCHLD will be sent anymore).
344 377
… …
770 803
771 AnyEvent::IGS 804 AnyEvent::IGS
772 A non-blocking interface to the Internet Go Server protocol (used by 805 A non-blocking interface to the Internet Go Server protocol (used by
773 App::IGS). 806 App::IGS).
774 807
808 AnyEvent::IRC
809 AnyEvent based IRC client module family (replacing the older
775 Net::IRC3 810 Net::IRC3).
776 AnyEvent based IRC client module family.
777 811
778 Net::XMPP2 812 Net::XMPP2
779 AnyEvent based XMPP (Jabber protocol) module family. 813 AnyEvent based XMPP (Jabber protocol) module family.
780 814
781 Net::FCP 815 Net::FCP
… …
790 824
791 IO::Lambda 825 IO::Lambda
792 The lambda approach to I/O - don't ask, look there. Can use 826 The lambda approach to I/O - don't ask, look there. Can use
793 AnyEvent. 827 AnyEvent.
794 828
795SUPPLYING YOUR OWN EVENT MODEL INTERFACE 829ERROR AND EXCEPTION HANDLING
796 This is an advanced topic that you do not normally need to use AnyEvent 830 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 831 caller to do that if required. The AnyEvent::Strict module (see also the
798 to provide AnyEvent compatibility. 832 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
833 checking of all AnyEvent methods, however, which is highly useful during
834 development.
799 835
800 If you need to support another event library which isn't directly 836 As for exception handling (i.e. runtime errors and exceptions thrown
801 supported by AnyEvent, you can supply your own interface to it by 837 while executing a callback), this is not only highly event-loop
802 pushing, before the first watcher gets created, the package name of the 838 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 839 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 840
807 Example: 841 The pure perl event loop simply re-throws the exception (usually within
808 842 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
809 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 843 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 844
838ENVIRONMENT VARIABLES 845ENVIRONMENT VARIABLES
839 The following environment variables are used by this module: 846 The following environment variables are used by this module or its
847 submodules:
840 848
841 "PERL_ANYEVENT_VERBOSE" 849 "PERL_ANYEVENT_VERBOSE"
842 By default, AnyEvent will be completely silent except in fatal 850 By default, AnyEvent will be completely silent except in fatal
843 conditions. You can set this environment variable to make AnyEvent 851 conditions. You can set this environment variable to make AnyEvent
844 more talkative. 852 more talkative.
… …
857 thoroughly check the arguments passed to most method calls. If it 865 thoroughly check the arguments passed to most method calls. If it
858 finds any problems it will croak. 866 finds any problems it will croak.
859 867
860 In other words, enables "strict" mode. 868 In other words, enables "strict" mode.
861 869
862 Unlike "use strict" it is definitely recommended ot keep it off in 870 Unlike "use strict", it is definitely recommended ot keep it off in
863 production. 871 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment
872 while developing programs can be very useful, however.
864 873
865 "PERL_ANYEVENT_MODEL" 874 "PERL_ANYEVENT_MODEL"
866 This can be used to specify the event model to be used by AnyEvent, 875 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 876 before auto detection and -probing kicks in. It must be a string
868 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 877 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
887 mentioned will be used, and preference will be given to protocols 896 mentioned will be used, and preference will be given to protocols
888 mentioned earlier in the list. 897 mentioned earlier in the list.
889 898
890 This variable can effectively be used for denial-of-service attacks 899 This variable can effectively be used for denial-of-service attacks
891 against local programs (e.g. when setuid), although the impact is 900 against local programs (e.g. when setuid), although the impact is
892 likely small, as the program has to handle connection errors 901 likely small, as the program has to handle conenction and other
893 already- 902 failures anyways.
894 903
895 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over 904 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
896 IPv6, but support both and try to use both. 905 IPv6, but support both and try to use both.
897 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to 906 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
898 resolve or contact IPv6 addresses. 907 resolve or contact IPv6 addresses.
… …
909 EDNS0 in its DNS requests. 918 EDNS0 in its DNS requests.
910 919
911 "PERL_ANYEVENT_MAX_FORKS" 920 "PERL_ANYEVENT_MAX_FORKS"
912 The maximum number of child processes that 921 The maximum number of child processes that
913 "AnyEvent::Util::fork_call" will create in parallel. 922 "AnyEvent::Util::fork_call" will create in parallel.
923
924SUPPLYING YOUR OWN EVENT MODEL INTERFACE
925 This is an advanced topic that you do not normally need to use AnyEvent
926 in a module. This section is only of use to event loop authors who want
927 to provide AnyEvent compatibility.
928
929 If you need to support another event library which isn't directly
930 supported by AnyEvent, you can supply your own interface to it by
931 pushing, before the first watcher gets created, the package name of the
932 event module and the package name of the interface to use onto
933 @AnyEvent::REGISTRY. You can do that before and even without loading
934 AnyEvent, so it is reasonably cheap.
935
936 Example:
937
938 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
939
940 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
941 package/class when it finds the "urxvt" package/module is already
942 loaded.
943
944 When AnyEvent is loaded and asked to find a suitable event model, it
945 will first check for the presence of urxvt by trying to "use" the
946 "urxvt::anyevent" module.
947
948 The class should provide implementations for all watcher types. See
949 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
950 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
951 the sources.
952
953 If you don't provide "signal" and "child" watchers than AnyEvent will
954 provide suitable (hopefully) replacements.
955
956 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
957 terminal emulator uses the above line as-is. An interface isn't included
958 in AnyEvent because it doesn't make sense outside the embedded
959 interpreter inside *rxvt-unicode*, and it is updated and maintained as
960 part of the *rxvt-unicode* distribution.
961
962 *rxvt-unicode* also cheats a bit by not providing blocking access to
963 condition variables: code blocking while waiting for a condition will
964 "die". This still works with most modules/usages, and blocking calls
965 must not be done in an interactive application, so it makes sense.
914 966
915EXAMPLE PROGRAM 967EXAMPLE PROGRAM
916 The following program uses an I/O watcher to read data from STDIN, a 968 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 969 timer to display a message once per second, and a condition variable to
918 quit the program when the user enters quit: 970 quit the program when the user enters quit:
… …
1105 *destroy* is the time, in microseconds, that it takes to destroy a 1157 *destroy* is the time, in microseconds, that it takes to destroy a
1106 single watcher. 1158 single watcher.
1107 1159
1108 Results 1160 Results
1109 name watchers bytes create invoke destroy comment 1161 name watchers bytes create invoke destroy comment
1110 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1162 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 1163 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 1164 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 1165 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 1166 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 1167 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 1168 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 1169 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 1170 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 1171 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
1120 1172
1121 Discussion 1173 Discussion
1122 The benchmark does *not* measure scalability of the event loop very 1174 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) 1175 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 1176 can never compete with an event loop that uses epoll when the number of
… …
1305 1357
1306 Summary 1358 Summary
1307 * C-based event loops perform very well with small number of watchers, 1359 * C-based event loops perform very well with small number of watchers,
1308 as the management overhead dominates. 1360 as the management overhead dominates.
1309 1361
1362SIGNALS
1363 AnyEvent currently installs handlers for these signals:
1364
1365 SIGCHLD
1366 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1367 emulation for event loops that do not support them natively. Also,
1368 some event loops install a similar handler.
1369
1370 SIGPIPE
1371 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1372 "undef" when AnyEvent gets loaded.
1373
1374 The rationale for this is that AnyEvent users usually do not really
1375 depend on SIGPIPE delivery (which is purely an optimisation for
1376 shell use, or badly-written programs), but "SIGPIPE" can cause
1377 spurious and rare program exits as a lot of people do not expect
1378 "SIGPIPE" when writing to some random socket.
1379
1380 The rationale for installing a no-op handler as opposed to ignoring
1381 it is that this way, the handler will be restored to defaults on
1382 exec.
1383
1384 Feel free to install your own handler, or reset it to defaults.
1385
1310FORK 1386FORK
1311 Most event libraries are not fork-safe. The ones who are usually are 1387 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. 1388 because they rely on inefficient but fork-safe "select" or "poll" calls.
1313 Only EV is fully fork-aware. 1389 Only EV is fully fork-aware.
1314 1390
… …
1337 1413
1338BUGS 1414BUGS
1339 Perl 5.8 has numerous memleaks that sometimes hit this module and are 1415 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1340 hard to work around. If you suffer from memleaks, first upgrade to Perl 1416 hard to work around. If you suffer from memleaks, first upgrade to Perl
1341 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other 1417 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
1342 annoying mamleaks, such as leaking on "map" and "grep" but it is usually 1418 annoying memleaks, such as leaking on "map" and "grep" but it is usually
1343 not as pronounced). 1419 not as pronounced).
1344 1420
1345SEE ALSO 1421SEE ALSO
1346 Utility functions: AnyEvent::Util. 1422 Utility functions: AnyEvent::Util.
1347 1423

Diff Legend

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