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.30 by root, Mon Sep 29 02:08:57 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
… …
790 797
791 IO::Lambda 798 IO::Lambda
792 The lambda approach to I/O - don't ask, look there. Can use 799 The lambda approach to I/O - don't ask, look there. Can use
793 AnyEvent. 800 AnyEvent.
794 801
795SUPPLYING YOUR OWN EVENT MODEL INTERFACE 802ERROR AND EXCEPTION HANDLING
796 This is an advanced topic that you do not normally need to use AnyEvent 803 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 804 caller to do that if required. The AnyEvent::Strict module (see also the
798 to provide AnyEvent compatibility. 805 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
806 checking of all AnyEvent methods, however, which is highly useful during
807 development.
799 808
800 If you need to support another event library which isn't directly 809 As for exception handling (i.e. runtime errors and exceptions thrown
801 supported by AnyEvent, you can supply your own interface to it by 810 while executing a callback), this is not only highly event-loop
802 pushing, before the first watcher gets created, the package name of the 811 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 812 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 813
807 Example: 814 The pure perl event loop simply re-throws the exception (usually within
808 815 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
809 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 816 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 817
838ENVIRONMENT VARIABLES 818ENVIRONMENT VARIABLES
839 The following environment variables are used by this module: 819 The following environment variables are used by this module or its
820 submodules:
840 821
841 "PERL_ANYEVENT_VERBOSE" 822 "PERL_ANYEVENT_VERBOSE"
842 By default, AnyEvent will be completely silent except in fatal 823 By default, AnyEvent will be completely silent except in fatal
843 conditions. You can set this environment variable to make AnyEvent 824 conditions. You can set this environment variable to make AnyEvent
844 more talkative. 825 more talkative.
… …
857 thoroughly check the arguments passed to most method calls. If it 838 thoroughly check the arguments passed to most method calls. If it
858 finds any problems it will croak. 839 finds any problems it will croak.
859 840
860 In other words, enables "strict" mode. 841 In other words, enables "strict" mode.
861 842
862 Unlike "use strict" it is definitely recommended ot keep it off in 843 Unlike "use strict", it is definitely recommended ot keep it off in
863 production. 844 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment
845 while developing programs can be very useful, however.
864 846
865 "PERL_ANYEVENT_MODEL" 847 "PERL_ANYEVENT_MODEL"
866 This can be used to specify the event model to be used by AnyEvent, 848 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 849 before auto detection and -probing kicks in. It must be a string
868 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 850 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
909 EDNS0 in its DNS requests. 891 EDNS0 in its DNS requests.
910 892
911 "PERL_ANYEVENT_MAX_FORKS" 893 "PERL_ANYEVENT_MAX_FORKS"
912 The maximum number of child processes that 894 The maximum number of child processes that
913 "AnyEvent::Util::fork_call" will create in parallel. 895 "AnyEvent::Util::fork_call" will create in parallel.
896
897SUPPLYING YOUR OWN EVENT MODEL INTERFACE
898 This is an advanced topic that you do not normally need to use AnyEvent
899 in a module. This section is only of use to event loop authors who want
900 to provide AnyEvent compatibility.
901
902 If you need to support another event library which isn't directly
903 supported by AnyEvent, you can supply your own interface to it by
904 pushing, before the first watcher gets created, the package name of the
905 event module and the package name of the interface to use onto
906 @AnyEvent::REGISTRY. You can do that before and even without loading
907 AnyEvent, so it is reasonably cheap.
908
909 Example:
910
911 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
912
913 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
914 package/class when it finds the "urxvt" package/module is already
915 loaded.
916
917 When AnyEvent is loaded and asked to find a suitable event model, it
918 will first check for the presence of urxvt by trying to "use" the
919 "urxvt::anyevent" module.
920
921 The class should provide implementations for all watcher types. See
922 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
923 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
924 the sources.
925
926 If you don't provide "signal" and "child" watchers than AnyEvent will
927 provide suitable (hopefully) replacements.
928
929 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
930 terminal emulator uses the above line as-is. An interface isn't included
931 in AnyEvent because it doesn't make sense outside the embedded
932 interpreter inside *rxvt-unicode*, and it is updated and maintained as
933 part of the *rxvt-unicode* distribution.
934
935 *rxvt-unicode* also cheats a bit by not providing blocking access to
936 condition variables: code blocking while waiting for a condition will
937 "die". This still works with most modules/usages, and blocking calls
938 must not be done in an interactive application, so it makes sense.
914 939
915EXAMPLE PROGRAM 940EXAMPLE PROGRAM
916 The following program uses an I/O watcher to read data from STDIN, a 941 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 942 timer to display a message once per second, and a condition variable to
918 quit the program when the user enters quit: 943 quit the program when the user enters quit:

Diff Legend

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