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.32 by root, Fri Oct 3 07:19:23 2008 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::"
… …
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:
… …
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