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

Comparing AnyEvent/README (file contents):
Revision 1.26 by root, Fri Jun 6 11:13:07 2008 UTC vs.
Revision 1.32 by root, Fri Oct 3 07:19:23 2008 UTC

… …
5 loops 5 loops
6 6
7SYNOPSIS 7SYNOPSIS
8 use AnyEvent; 8 use AnyEvent;
9 9
10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { 10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { ... });
11 ...
12 });
13 11
14 my $w = AnyEvent->timer (after => $seconds, cb => sub { 12 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
13 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
14
15 print AnyEvent->now; # prints current event loop time
16 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
17
18 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
19
20 my $w = AnyEvent->child (pid => $pid, cb => sub {
21 my ($pid, $status) = @_;
15 ... 22 ...
16 }); 23 });
17 24
18 my $w = AnyEvent->condvar; # stores whether a condition was flagged 25 my $w = AnyEvent->condvar; # stores whether a condition was flagged
19 $w->send; # wake up current and all future recv's 26 $w->send; # wake up current and all future recv's
20 $w->recv; # enters "main loop" till $condvar gets ->send 27 $w->recv; # enters "main loop" till $condvar gets ->send
28 # use a condvar in callback mode:
29 $w->cb (sub { $_[0]->recv });
21 30
22INTRODUCTION/TUTORIAL 31INTRODUCTION/TUTORIAL
23 This manpage is mainly a reference manual. If you are interested in a 32 This manpage is mainly a reference manual. If you are interested in a
24 tutorial or some gentle introduction, have a look at the AnyEvent::Intro 33 tutorial or some gentle introduction, have a look at the AnyEvent::Intro
25 manpage. 34 manpage.
… …
30 39
31 Executive Summary: AnyEvent is *compatible*, AnyEvent is *free of 40 Executive Summary: AnyEvent is *compatible*, AnyEvent is *free of
32 policy* and AnyEvent is *small and efficient*. 41 policy* and AnyEvent is *small and efficient*.
33 42
34 First and foremost, *AnyEvent is not an event model* itself, it only 43 First and foremost, *AnyEvent is not an event model* itself, it only
35 interfaces to whatever event model the main program happens to use in a 44 interfaces to whatever event model the main program happens to use, in a
36 pragmatic way. For event models and certain classes of immortals alike, 45 pragmatic way. For event models and certain classes of immortals alike,
37 the statement "there can only be one" is a bitter reality: In general, 46 the statement "there can only be one" is a bitter reality: In general,
38 only one event loop can be active at the same time in a process. 47 only one event loop can be active at the same time in a process.
39 AnyEvent helps hiding the differences between those event loops. 48 AnyEvent cannot change this, but it can hide the differences between
49 those event loops.
40 50
41 The goal of AnyEvent is to offer module authors the ability to do event 51 The goal of AnyEvent is to offer module authors the ability to do event
42 programming (waiting for I/O or timer events) without subscribing to a 52 programming (waiting for I/O or timer events) without subscribing to a
43 religion, a way of living, and most importantly: without forcing your 53 religion, a way of living, and most importantly: without forcing your
44 module users into the same thing by forcing them to use the same event 54 module users into the same thing by forcing them to use the same event
45 model you use. 55 model you use.
46 56
47 For modules like POE or IO::Async (which is a total misnomer as it is 57 For modules like POE or IO::Async (which is a total misnomer as it is
48 actually doing all I/O *synchronously*...), using them in your module is 58 actually doing all I/O *synchronously*...), using them in your module is
49 like joining a cult: After you joined, you are dependent on them and you 59 like joining a cult: After you joined, you are dependent on them and you
50 cannot use anything else, as it is simply incompatible to everything 60 cannot use anything else, as they are simply incompatible to everything
51 that isn't itself. What's worse, all the potential users of your module 61 that isn't them. What's worse, all the potential users of your module
52 are *also* forced to use the same event loop you use. 62 are *also* forced to use the same event loop you use.
53 63
54 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 64 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
55 fine. AnyEvent + Tk works fine etc. etc. but none of these work together 65 fine. AnyEvent + Tk works fine etc. etc. but none of these work together
56 with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if your 66 with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if your
57 module uses one of those, every user of your module has to use it, too. 67 module uses one of those, every user of your module has to use it, too.
58 But if your module uses AnyEvent, it works transparently with all event 68 But if your module uses AnyEvent, it works transparently with all event
59 models it supports (including stuff like POE and IO::Async, as long as 69 models it supports (including stuff like IO::Async, as long as those use
60 those use one of the supported event loops. It is trivial to add new 70 one of the supported event loops. It is trivial to add new event loops
61 event loops to AnyEvent, too, so it is future-proof). 71 to AnyEvent, too, so it is future-proof).
62 72
63 In addition to being free of having to use *the one and only true event 73 In addition to being free of having to use *the one and only true event
64 model*, AnyEvent also is free of bloat and policy: with POE or similar 74 model*, AnyEvent also is free of bloat and policy: with POE or similar
65 modules, you get an enormous amount of code and strict rules you have to 75 modules, you get an enormous amount of code and strict rules you have to
66 follow. AnyEvent, on the other hand, is lean and up to the point, by 76 follow. AnyEvent, on the other hand, is lean and up to the point, by
… …
146 156
147 I/O WATCHERS 157 I/O WATCHERS
148 You can create an I/O watcher by calling the "AnyEvent->io" method with 158 You can create an I/O watcher by calling the "AnyEvent->io" method with
149 the following mandatory key-value pairs as arguments: 159 the following mandatory key-value pairs as arguments:
150 160
151 "fh" the Perl *file handle* (*not* file descriptor) to watch for events. 161 "fh" the Perl *file handle* (*not* file descriptor) to watch for events
162 (AnyEvent might or might not keep a reference to this file handle).
152 "poll" must be a string that is either "r" or "w", which creates a 163 "poll" must be a string that is either "r" or "w", which creates a
153 watcher waiting for "r"eadable or "w"ritable events, respectively. "cb" 164 watcher waiting for "r"eadable or "w"ritable events, respectively. "cb"
154 is the callback to invoke each time the file handle becomes ready. 165 is the callback to invoke each time the file handle becomes ready.
155 166
156 Although the callback might get passed parameters, their value and 167 Although the callback might get passed parameters, their value and
… …
163 174
164 Some event loops issue spurious readyness notifications, so you should 175 Some event loops issue spurious readyness notifications, so you should
165 always use non-blocking calls when reading/writing from/to your file 176 always use non-blocking calls when reading/writing from/to your file
166 handles. 177 handles.
167 178
168 Example:
169
170 # wait for readability of STDIN, then read a line and disable the watcher 179 Example: wait for readability of STDIN, then read a line and disable the
180 watcher.
181
171 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 182 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
172 chomp (my $input = <STDIN>); 183 chomp (my $input = <STDIN>);
173 warn "read: $input\n"; 184 warn "read: $input\n";
174 undef $w; 185 undef $w;
175 }); 186 });
… …
184 195
185 Although the callback might get passed parameters, their value and 196 Although the callback might get passed parameters, their value and
186 presence is undefined and you cannot rely on them. Portable AnyEvent 197 presence is undefined and you cannot rely on them. Portable AnyEvent
187 callbacks cannot use arguments passed to time watcher callbacks. 198 callbacks cannot use arguments passed to time watcher callbacks.
188 199
189 The timer callback will be invoked at most once: if you want a repeating 200 The callback will normally be invoked once only. If you specify another
190 timer you have to create a new watcher (this is a limitation by both Tk 201 parameter, "interval", as a strictly positive number (> 0), then the
191 and Glib). 202 callback will be invoked regularly at that interval (in fractional
203 seconds) after the first invocation. If "interval" is specified with a
204 false value, then it is treated as if it were missing.
192 205
193 Example: 206 The callback will be rescheduled before invoking the callback, but no
207 attempt is done to avoid timer drift in most backends, so the interval
208 is only approximate.
194 209
195 # fire an event after 7.7 seconds 210 Example: fire an event after 7.7 seconds.
211
196 my $w = AnyEvent->timer (after => 7.7, cb => sub { 212 my $w = AnyEvent->timer (after => 7.7, cb => sub {
197 warn "timeout\n"; 213 warn "timeout\n";
198 }); 214 });
199 215
200 # to cancel the timer: 216 # to cancel the timer:
201 undef $w; 217 undef $w;
202 218
203 Example 2:
204
205 # fire an event after 0.5 seconds, then roughly every second 219 Example 2: fire an event after 0.5 seconds, then roughly every second.
206 my $w;
207 220
208 my $cb = sub {
209 # cancel the old timer while creating a new one
210 $w = AnyEvent->timer (after => 1, cb => $cb); 221 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
222 warn "timeout\n";
211 }; 223 };
212
213 # start the "loop" by creating the first watcher
214 $w = AnyEvent->timer (after => 0.5, cb => $cb);
215 224
216 TIMING ISSUES 225 TIMING ISSUES
217 There are two ways to handle timers: based on real time (relative, "fire 226 There are two ways to handle timers: based on real time (relative, "fire
218 in 10 seconds") and based on wallclock time (absolute, "fire at 12 227 in 10 seconds") and based on wallclock time (absolute, "fire at 12
219 o'clock"). 228 o'clock").
… …
295 the difference between "AnyEvent->time" and "AnyEvent->now" into 304 the difference between "AnyEvent->time" and "AnyEvent->now" into
296 account. 305 account.
297 306
298 SIGNAL WATCHERS 307 SIGNAL WATCHERS
299 You can watch for signals using a signal watcher, "signal" is the signal 308 You can watch for signals using a signal watcher, "signal" is the signal
300 *name* without any "SIG" prefix, "cb" is the Perl callback to be invoked 309 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl
301 whenever a signal occurs. 310 callback to be invoked whenever a signal occurs.
302 311
303 Although the callback might get passed parameters, their value and 312 Although the callback might get passed parameters, their value and
304 presence is undefined and you cannot rely on them. Portable AnyEvent 313 presence is undefined and you cannot rely on them. Portable AnyEvent
305 callbacks cannot use arguments passed to signal watcher callbacks. 314 callbacks cannot use arguments passed to signal watcher callbacks.
306 315
… …
321 330
322 CHILD PROCESS WATCHERS 331 CHILD PROCESS WATCHERS
323 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.
324 333
325 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
326 watches for any child process exit). The watcher will trigger as often 335 watches for any child process exit). The watcher will triggered only
327 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
328 signal handler for "SIGCHLD". The callback will be called with the pid 337 on any trace events (stopped/continued).
329 and exit status (as returned by waitpid), so unlike other watcher types, 338
330 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).
331 347
332 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
333 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
334 could have exited already (and no SIGCHLD will be sent anymore). 350 could have exited already (and no SIGCHLD will be sent anymore).
335 351
… …
371 The instrument to do that is called a "condition variable", so called 387 The instrument to do that is called a "condition variable", so called
372 because they represent a condition that must become true. 388 because they represent a condition that must become true.
373 389
374 Condition variables can be created by calling the "AnyEvent->condvar" 390 Condition variables can be created by calling the "AnyEvent->condvar"
375 method, usually without arguments. The only argument pair allowed is 391 method, usually without arguments. The only argument pair allowed is
392
376 "cb", which specifies a callback to be called when the condition 393 "cb", which specifies a callback to be called when the condition
377 variable becomes true. 394 variable becomes true, with the condition variable as the first argument
395 (but not the results).
378 396
379 After creation, the condition variable is "false" until it becomes 397 After creation, the condition variable is "false" until it becomes
380 "true" by calling the "send" method (or calling the condition variable 398 "true" by calling the "send" method (or calling the condition variable
381 as if it were a callback, read about the caveats in the description for 399 as if it were a callback, read about the caveats in the description for
382 the "->send" method). 400 the "->send" method).
… …
438 456
439 my $done = AnyEvent->condvar; 457 my $done = AnyEvent->condvar;
440 my $delay = AnyEvent->timer (after => 5, cb => $done); 458 my $delay = AnyEvent->timer (after => 5, cb => $done);
441 $done->recv; 459 $done->recv;
442 460
461 Example: Imagine an API that returns a condvar and doesn't support
462 callbacks. This is how you make a synchronous call, for example from the
463 main program:
464
465 use AnyEvent::CouchDB;
466
467 ...
468
469 my @info = $couchdb->info->recv;
470
471 And this is how you would just ste a callback to be called whenever the
472 results are available:
473
474 $couchdb->info->cb (sub {
475 my @info = $_[0]->recv;
476 });
477
443 METHODS FOR PRODUCERS 478 METHODS FOR PRODUCERS
444 These methods should only be used by the producing side, i.e. the 479 These methods should only be used by the producing side, i.e. the
445 code/module that eventually sends the signal. Note that it is also the 480 code/module that eventually sends the signal. Note that it is also the
446 producer side which creates the condvar in most cases, but it isn't 481 producer side which creates the condvar in most cases, but it isn't
447 uncommon for the consumer to create it as well. 482 uncommon for the consumer to create it as well.
… …
567 602
568 $bool = $cv->ready 603 $bool = $cv->ready
569 Returns true when the condition is "true", i.e. whether "send" or 604 Returns true when the condition is "true", i.e. whether "send" or
570 "croak" have been called. 605 "croak" have been called.
571 606
572 $cb = $cv->cb ([new callback]) 607 $cb = $cv->cb ($cb->($cv))
573 This is a mutator function that returns the callback set and 608 This is a mutator function that returns the callback set and
574 optionally replaces it before doing so. 609 optionally replaces it before doing so.
575 610
576 The callback will be called when the condition becomes "true", i.e. 611 The callback will be called when the condition becomes "true", i.e.
577 when "send" or "croak" are called, with the only argument being the 612 when "send" or "croak" are called, with the only argument being the
… …
698 AnyEvent::Util 733 AnyEvent::Util
699 Contains various utility functions that replace often-used but 734 Contains various utility functions that replace often-used but
700 blocking functions such as "inet_aton" by event-/callback-based 735 blocking functions such as "inet_aton" by event-/callback-based
701 versions. 736 versions.
702 737
703 AnyEvent::Handle
704 Provide read and write buffers and manages watchers for reads and
705 writes.
706
707 AnyEvent::Socket 738 AnyEvent::Socket
708 Provides various utility functions for (internet protocol) sockets, 739 Provides various utility functions for (internet protocol) sockets,
709 addresses and name resolution. Also functions to create non-blocking 740 addresses and name resolution. Also functions to create non-blocking
710 tcp connections or tcp servers, with IPv6 and SRV record support and 741 tcp connections or tcp servers, with IPv6 and SRV record support and
711 more. 742 more.
712 743
744 AnyEvent::Handle
745 Provide read and write buffers, manages watchers for reads and
746 writes, supports raw and formatted I/O, I/O queued and fully
747 transparent and non-blocking SSL/TLS.
748
713 AnyEvent::DNS 749 AnyEvent::DNS
714 Provides rich asynchronous DNS resolver capabilities. 750 Provides rich asynchronous DNS resolver capabilities.
715 751
716 AnyEvent::HTTP 752 AnyEvent::HTTP
717 A simple-to-use HTTP library that is capable of making a lot of 753 A simple-to-use HTTP library that is capable of making a lot of
… …
721 Provides a simple web application server framework. 757 Provides a simple web application server framework.
722 758
723 AnyEvent::FastPing 759 AnyEvent::FastPing
724 The fastest ping in the west. 760 The fastest ping in the west.
725 761
762 AnyEvent::DBI
763 Executes DBI requests asynchronously in a proxy process.
764
765 AnyEvent::AIO
766 Truly asynchronous I/O, should be in the toolbox of every event
767 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
768 together.
769
770 AnyEvent::BDB
771 Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently
772 fuses BDB and AnyEvent together.
773
774 AnyEvent::GPSD
775 A non-blocking interface to gpsd, a daemon delivering GPS
776 information.
777
778 AnyEvent::IGS
779 A non-blocking interface to the Internet Go Server protocol (used by
780 App::IGS).
781
782 AnyEvent::IRC
783 AnyEvent based IRC client module family (replacing the older
726 Net::IRC3 784 Net::IRC3).
727 AnyEvent based IRC client module family.
728 785
729 Net::XMPP2 786 Net::XMPP2
730 AnyEvent based XMPP (Jabber protocol) module family. 787 AnyEvent based XMPP (Jabber protocol) module family.
731 788
732 Net::FCP 789 Net::FCP
… …
737 High level API for event-based execution flow control. 794 High level API for event-based execution flow control.
738 795
739 Coro 796 Coro
740 Has special support for AnyEvent via Coro::AnyEvent. 797 Has special support for AnyEvent via Coro::AnyEvent.
741 798
742 AnyEvent::AIO, IO::AIO
743 Truly asynchronous I/O, should be in the toolbox of every event
744 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
745 together.
746
747 AnyEvent::BDB, BDB
748 Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently
749 fuses IO::AIO and AnyEvent together.
750
751 IO::Lambda 799 IO::Lambda
752 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
753 AnyEvent. 801 AnyEvent.
754 802
755SUPPLYING YOUR OWN EVENT MODEL INTERFACE 803ERROR AND EXCEPTION HANDLING
756 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
757 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
758 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.
759 809
760 If you need to support another event library which isn't directly 810 As for exception handling (i.e. runtime errors and exceptions thrown
761 supported by AnyEvent, you can supply your own interface to it by 811 while executing a callback), this is not only highly event-loop
762 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
763 event module and the package name of the interface to use onto 813 job of the main program.
764 @AnyEvent::REGISTRY. You can do that before and even without loading
765 AnyEvent, so it is reasonably cheap.
766 814
767 Example: 815 The pure perl event loop simply re-throws the exception (usually within
768 816 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
769 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 817 Glib uses "install_exception_handler" and so on.
770
771 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
772 package/class when it finds the "urxvt" package/module is already
773 loaded.
774
775 When AnyEvent is loaded and asked to find a suitable event model, it
776 will first check for the presence of urxvt by trying to "use" the
777 "urxvt::anyevent" module.
778
779 The class should provide implementations for all watcher types. See
780 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
781 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
782 the sources.
783
784 If you don't provide "signal" and "child" watchers than AnyEvent will
785 provide suitable (hopefully) replacements.
786
787 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
788 terminal emulator uses the above line as-is. An interface isn't included
789 in AnyEvent because it doesn't make sense outside the embedded
790 interpreter inside *rxvt-unicode*, and it is updated and maintained as
791 part of the *rxvt-unicode* distribution.
792
793 *rxvt-unicode* also cheats a bit by not providing blocking access to
794 condition variables: code blocking while waiting for a condition will
795 "die". This still works with most modules/usages, and blocking calls
796 must not be done in an interactive application, so it makes sense.
797 818
798ENVIRONMENT VARIABLES 819ENVIRONMENT VARIABLES
799 The following environment variables are used by this module: 820 The following environment variables are used by this module or its
821 submodules:
800 822
801 "PERL_ANYEVENT_VERBOSE" 823 "PERL_ANYEVENT_VERBOSE"
802 By default, AnyEvent will be completely silent except in fatal 824 By default, AnyEvent will be completely silent except in fatal
803 conditions. You can set this environment variable to make AnyEvent 825 conditions. You can set this environment variable to make AnyEvent
804 more talkative. 826 more talkative.
… …
807 conditions, such as not being able to load the event model specified 829 conditions, such as not being able to load the event model specified
808 by "PERL_ANYEVENT_MODEL". 830 by "PERL_ANYEVENT_MODEL".
809 831
810 When set to 2 or higher, cause AnyEvent to report to STDERR which 832 When set to 2 or higher, cause AnyEvent to report to STDERR which
811 event model it chooses. 833 event model it chooses.
834
835 "PERL_ANYEVENT_STRICT"
836 AnyEvent does not do much argument checking by default, as thorough
837 argument checking is very costly. Setting this variable to a true
838 value will cause AnyEvent to load "AnyEvent::Strict" and then to
839 thoroughly check the arguments passed to most method calls. If it
840 finds any problems it will croak.
841
842 In other words, enables "strict" mode.
843
844 Unlike "use strict", it is definitely recommended ot keep it off in
845 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment
846 while developing programs can be very useful, however.
812 847
813 "PERL_ANYEVENT_MODEL" 848 "PERL_ANYEVENT_MODEL"
814 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,
815 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
816 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 851 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
857 EDNS0 in its DNS requests. 892 EDNS0 in its DNS requests.
858 893
859 "PERL_ANYEVENT_MAX_FORKS" 894 "PERL_ANYEVENT_MAX_FORKS"
860 The maximum number of child processes that 895 The maximum number of child processes that
861 "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.
862 940
863EXAMPLE PROGRAM 941EXAMPLE PROGRAM
864 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
865 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
866 quit the program when the user enters quit: 944 quit the program when the user enters quit:
… …
1253 1331
1254 Summary 1332 Summary
1255 * 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,
1256 as the management overhead dominates. 1334 as the management overhead dominates.
1257 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
1258FORK 1360FORK
1259 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
1260 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.
1261 Only EV is fully fork-aware. 1363 Only EV is fully fork-aware.
1262 1364
… …
1278 1380
1279 use AnyEvent; 1381 use AnyEvent;
1280 1382
1281 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1383 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1282 be used to probe what backend is used and gain other information (which 1384 be used to probe what backend is used and gain other information (which
1283 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1385 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
1386 and $ENV{PERL_ANYEGENT_STRICT}.
1284 1387
1285BUGS 1388BUGS
1286 Perl 5.8 has numerous memleaks that sometimes hit this module and are 1389 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1287 hard to work around. If you suffer from memleaks, first upgrade to Perl 1390 hard to work around. If you suffer from memleaks, first upgrade to Perl
1288 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other 1391 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other

Diff Legend

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