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

Comparing AnyEvent/README (file contents):
Revision 1.62 by root, Sun Jun 6 10:13:57 2010 UTC vs.
Revision 1.63 by root, Wed Oct 13 19:49:46 2010 UTC

13 # file handle or descriptor readable 13 # file handle or descriptor readable
14 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... }); 14 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
15 15
16 # one-shot or repeating timers 16 # one-shot or repeating timers
17 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... }); 17 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
18 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ... 18 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...);
19 19
20 print AnyEvent->now; # prints current event loop time 20 print AnyEvent->now; # prints current event loop time
21 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time. 21 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
22 22
23 # POSIX signal 23 # POSIX signal
42 This manpage is mainly a reference manual. If you are interested in a 42 This manpage is mainly a reference manual. If you are interested in a
43 tutorial or some gentle introduction, have a look at the AnyEvent::Intro 43 tutorial or some gentle introduction, have a look at the AnyEvent::Intro
44 manpage. 44 manpage.
45 45
46SUPPORT 46SUPPORT
47 An FAQ document is available as AnyEvent::FAQ.
48
47 There is a mailinglist for discussing all things AnyEvent, and an IRC 49 There also is a mailinglist for discussing all things AnyEvent, and an
48 channel, too. 50 IRC channel, too.
49 51
50 See the AnyEvent project page at the Schmorpforge Ta-Sa Software 52 See the AnyEvent project page at the Schmorpforge Ta-Sa Software
51 Repository, at <http://anyevent.schmorp.de>, for more info. 53 Repository, at <http://anyevent.schmorp.de>, for more info.
52 54
53WHY YOU SHOULD USE THIS MODULE (OR NOT) 55WHY YOU SHOULD USE THIS MODULE (OR NOT)
71 module users into the same thing by forcing them to use the same event 73 module users into the same thing by forcing them to use the same event
72 model you use. 74 model you use.
73 75
74 For modules like POE or IO::Async (which is a total misnomer as it is 76 For modules like POE or IO::Async (which is a total misnomer as it is
75 actually doing all I/O *synchronously*...), using them in your module is 77 actually doing all I/O *synchronously*...), using them in your module is
76 like joining a cult: After you joined, you are dependent on them and you 78 like joining a cult: After you join, you are dependent on them and you
77 cannot use anything else, as they are simply incompatible to everything 79 cannot use anything else, as they are simply incompatible to everything
78 that isn't them. What's worse, all the potential users of your module 80 that isn't them. What's worse, all the potential users of your module
79 are *also* forced to use the same event loop you use. 81 are *also* forced to use the same event loop you use.
80 82
81 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 83 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
82 fine. AnyEvent + Tk works fine etc. etc. but none of these work together 84 fine. AnyEvent + Tk works fine etc. etc. but none of these work together
83 with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if your 85 with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if your
84 module uses one of those, every user of your module has to use it, too. 86 module uses one of those, every user of your module has to use it, too.
85 But if your module uses AnyEvent, it works transparently with all event 87 But if your module uses AnyEvent, it works transparently with all event
86 models it supports (including stuff like IO::Async, as long as those use 88 models it supports (including stuff like IO::Async, as long as those use
87 one of the supported event loops. It is trivial to add new event loops 89 one of the supported event loops. It is easy to add new event loops to
88 to AnyEvent, too, so it is future-proof). 90 AnyEvent, too, so it is future-proof).
89 91
90 In addition to being free of having to use *the one and only true event 92 In addition to being free of having to use *the one and only true event
91 model*, AnyEvent also is free of bloat and policy: with POE or similar 93 model*, AnyEvent also is free of bloat and policy: with POE or similar
92 modules, you get an enormous amount of code and strict rules you have to 94 modules, you get an enormous amount of code and strict rules you have to
93 follow. AnyEvent, on the other hand, is lean and up to the point, by 95 follow. AnyEvent, on the other hand, is lean and to the point, by only
94 only offering the functionality that is necessary, in as thin as a 96 offering the functionality that is necessary, in as thin as a wrapper as
95 wrapper as technically possible. 97 technically possible.
96 98
97 Of course, AnyEvent comes with a big (and fully optional!) toolbox of 99 Of course, AnyEvent comes with a big (and fully optional!) toolbox of
98 useful functionality, such as an asynchronous DNS resolver, 100% 100 useful functionality, such as an asynchronous DNS resolver, 100%
99 non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms 101 non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms
100 such as Windows) and lots of real-world knowledge and workarounds for 102 such as Windows) and lots of real-world knowledge and workarounds for
103 Now, if you *do want* lots of policy (this can arguably be somewhat 105 Now, if you *do want* lots of policy (this can arguably be somewhat
104 useful) and you want to force your users to use the one and only event 106 useful) and you want to force your users to use the one and only event
105 model, you should *not* use this module. 107 model, you should *not* use this module.
106 108
107DESCRIPTION 109DESCRIPTION
108 AnyEvent provides an identical interface to multiple event loops. This 110 AnyEvent provides a uniform interface to various event loops. This
109 allows module authors to utilise an event loop without forcing module 111 allows module authors to use event loop functionality without forcing
110 users to use the same event loop (as only a single event loop can 112 module users to use a specific event loop implementation (since more
111 coexist peacefully at any one time). 113 than one event loop cannot coexist peacefully).
112 114
113 The interface itself is vaguely similar, but not identical to the Event 115 The interface itself is vaguely similar, but not identical to the Event
114 module. 116 module.
115 117
116 During the first call of any watcher-creation method, the module tries 118 During the first call of any watcher-creation method, the module tries
117 to detect the currently loaded event loop by probing whether one of the 119 to detect the currently loaded event loop by probing whether one of the
118 following modules is already loaded: EV, Event, Glib, 120 following modules is already loaded: EV, AnyEvent::Impl::Perl, Event,
119 AnyEvent::Impl::Perl, Tk, Event::Lib, Qt, POE. The first one found is 121 Glib, Tk, Event::Lib, Qt, POE. The first one found is used. If none are
120 used. If none are found, the module tries to load these modules 122 detected, the module tries to load the first four modules in the order
121 (excluding Tk, Event::Lib, Qt and POE as the pure perl adaptor should 123 given; but note that if EV is not available, the pure-perl
122 always succeed) in the order given. The first one that can be 124 AnyEvent::Impl::Perl should always work, so the other two are not
123 successfully loaded will be used. If, after this, still none could be 125 normally tried.
124 found, AnyEvent will fall back to a pure-perl event loop, which is not
125 very efficient, but should work everywhere.
126 126
127 Because AnyEvent first checks for modules that are already loaded, 127 Because AnyEvent first checks for modules that are already loaded,
128 loading an event model explicitly before first using AnyEvent will 128 loading an event model explicitly before first using AnyEvent will
129 likely make that model the default. For example: 129 likely make that model the default. For example:
130 130
132 use AnyEvent; 132 use AnyEvent;
133 133
134 # .. AnyEvent will likely default to Tk 134 # .. AnyEvent will likely default to Tk
135 135
136 The *likely* means that, if any module loads another event model and 136 The *likely* means that, if any module loads another event model and
137 starts using it, all bets are off. Maybe you should tell their authors 137 starts using it, all bets are off - this case should be very rare
138 to use AnyEvent so their modules work together with others seamlessly... 138 though, as very few modules hardcode event loops without announcing this
139 very loudly.
139 140
140 The pure-perl implementation of AnyEvent is called 141 The pure-perl implementation of AnyEvent is called
141 "AnyEvent::Impl::Perl". Like other event modules you can load it 142 "AnyEvent::Impl::Perl". Like other event modules you can load it
142 explicitly and enjoy the high availability of that event loop :) 143 explicitly and enjoy the high availability of that event loop :)
143 144
151 callback when the event occurs (of course, only when the event model is 152 callback when the event occurs (of course, only when the event model is
152 in control). 153 in control).
153 154
154 Note that callbacks must not permanently change global variables 155 Note that callbacks must not permanently change global variables
155 potentially in use by the event loop (such as $_ or $[) and that 156 potentially in use by the event loop (such as $_ or $[) and that
156 callbacks must not "die". The former is good programming practise in 157 callbacks must not "die". The former is good programming practice in
157 Perl and the latter stems from the fact that exception handling differs 158 Perl and the latter stems from the fact that exception handling differs
158 widely between event loops. 159 widely between event loops.
159 160
160 To disable the watcher you have to destroy it (e.g. by setting the 161 To disable a watcher you have to destroy it (e.g. by setting the
161 variable you store it in to "undef" or otherwise deleting all references 162 variable you store it in to "undef" or otherwise deleting all references
162 to it). 163 to it).
163 164
164 All watchers are created by calling a method on the "AnyEvent" class. 165 All watchers are created by calling a method on the "AnyEvent" class.
165 166
166 Many watchers either are used with "recursion" (repeating timers for 167 Many watchers either are used with "recursion" (repeating timers for
167 example), or need to refer to their watcher object in other ways. 168 example), or need to refer to their watcher object in other ways.
168 169
169 An any way to achieve that is this pattern: 170 One way to achieve that is this pattern:
170 171
171 my $w; $w = AnyEvent->type (arg => value ..., cb => sub { 172 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
172 # you can use $w here, for example to undef it 173 # you can use $w here, for example to undef it
173 undef $w; 174 undef $w;
174 }); 175 });
205 206
206 The I/O watcher might use the underlying file descriptor or a copy of 207 The I/O watcher might use the underlying file descriptor or a copy of
207 it. You must not close a file handle as long as any watcher is active on 208 it. You must not close a file handle as long as any watcher is active on
208 the underlying file descriptor. 209 the underlying file descriptor.
209 210
210 Some event loops issue spurious readyness notifications, so you should 211 Some event loops issue spurious readiness notifications, so you should
211 always use non-blocking calls when reading/writing from/to your file 212 always use non-blocking calls when reading/writing from/to your file
212 handles. 213 handles.
213 214
214 Example: wait for readability of STDIN, then read a line and disable the 215 Example: wait for readability of STDIN, then read a line and disable the
215 watcher. 216 watcher.
238 239
239 Although the callback might get passed parameters, their value and 240 Although the callback might get passed parameters, their value and
240 presence is undefined and you cannot rely on them. Portable AnyEvent 241 presence is undefined and you cannot rely on them. Portable AnyEvent
241 callbacks cannot use arguments passed to time watcher callbacks. 242 callbacks cannot use arguments passed to time watcher callbacks.
242 243
243 The callback will normally be invoked once only. If you specify another 244 The callback will normally be invoked only once. If you specify another
244 parameter, "interval", as a strictly positive number (> 0), then the 245 parameter, "interval", as a strictly positive number (> 0), then the
245 callback will be invoked regularly at that interval (in fractional 246 callback will be invoked regularly at that interval (in fractional
246 seconds) after the first invocation. If "interval" is specified with a 247 seconds) after the first invocation. If "interval" is specified with a
247 false value, then it is treated as if it were missing. 248 false value, then it is treated as if it were not specified at all.
248 249
249 The callback will be rescheduled before invoking the callback, but no 250 The callback will be rescheduled before invoking the callback, but no
250 attempt is done to avoid timer drift in most backends, so the interval 251 attempt is made to avoid timer drift in most backends, so the interval
251 is only approximate. 252 is only approximate.
252 253
253 Example: fire an event after 7.7 seconds. 254 Example: fire an event after 7.7 seconds.
254 255
255 my $w = AnyEvent->timer (after => 7.7, cb => sub { 256 my $w = AnyEvent->timer (after => 7.7, cb => sub {
272 273
273 While most event loops expect timers to specified in a relative way, 274 While most event loops expect timers to specified in a relative way,
274 they use absolute time internally. This makes a difference when your 275 they use absolute time internally. This makes a difference when your
275 clock "jumps", for example, when ntp decides to set your clock backwards 276 clock "jumps", for example, when ntp decides to set your clock backwards
276 from the wrong date of 2014-01-01 to 2008-01-01, a watcher that is 277 from the wrong date of 2014-01-01 to 2008-01-01, a watcher that is
277 supposed to fire "after" a second might actually take six years to 278 supposed to fire "after a second" might actually take six years to
278 finally fire. 279 finally fire.
279 280
280 AnyEvent cannot compensate for this. The only event loop that is 281 AnyEvent cannot compensate for this. The only event loop that is
281 conscious about these issues is EV, which offers both relative 282 conscious of these issues is EV, which offers both relative (ev_timer,
282 (ev_timer, based on true relative time) and absolute (ev_periodic, based 283 based on true relative time) and absolute (ev_periodic, based on
283 on wallclock time) timers. 284 wallclock time) timers.
284 285
285 AnyEvent always prefers relative timers, if available, matching the 286 AnyEvent always prefers relative timers, if available, matching the
286 AnyEvent API. 287 AnyEvent API.
287 288
288 AnyEvent has two additional methods that return the "current time": 289 AnyEvent has two additional methods that return the "current time":
307 *In almost all cases (in all cases if you don't care), this is the 308 *In almost all cases (in all cases if you don't care), this is the
308 function to call when you want to know the current time.* 309 function to call when you want to know the current time.*
309 310
310 This function is also often faster then "AnyEvent->time", and thus 311 This function is also often faster then "AnyEvent->time", and thus
311 the preferred method if you want some timestamp (for example, 312 the preferred method if you want some timestamp (for example,
312 AnyEvent::Handle uses this to update it's activity timeouts). 313 AnyEvent::Handle uses this to update its activity timeouts).
313 314
314 The rest of this section is only of relevance if you try to be very 315 The rest of this section is only of relevance if you try to be very
315 exact with your timing, you can skip it without bad conscience. 316 exact with your timing; you can skip it without a bad conscience.
316 317
317 For a practical example of when these times differ, consider 318 For a practical example of when these times differ, consider
318 Event::Lib and EV and the following set-up: 319 Event::Lib and EV and the following set-up:
319 320
320 The event loop is running and has just invoked one of your callback 321 The event loop is running and has just invoked one of your callbacks
321 at time=500 (assume no other callbacks delay processing). In your 322 at time=500 (assume no other callbacks delay processing). In your
322 callback, you wait a second by executing "sleep 1" (blocking the 323 callback, you wait a second by executing "sleep 1" (blocking the
323 process for a second) and then (at time=501) you create a relative 324 process for a second) and then (at time=501) you create a relative
324 timer that fires after three seconds. 325 timer that fires after three seconds.
325 326
414 415
415 Signal Races, Delays and Workarounds 416 Signal Races, Delays and Workarounds
416 Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching 417 Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
417 callbacks to signals in a generic way, which is a pity, as you cannot do 418 callbacks to signals in a generic way, which is a pity, as you cannot do
418 race-free signal handling in perl, requiring C libraries for this. 419 race-free signal handling in perl, requiring C libraries for this.
419 AnyEvent will try to do it's best, which means in some cases, signals 420 AnyEvent will try to do its best, which means in some cases, signals
420 will be delayed. The maximum time a signal might be delayed is specified 421 will be delayed. The maximum time a signal might be delayed is specified
421 in $AnyEvent::MAX_SIGNAL_LATENCY (default: 10 seconds). This variable 422 in $AnyEvent::MAX_SIGNAL_LATENCY (default: 10 seconds). This variable
422 can be changed only before the first signal watcher is created, and 423 can be changed only before the first signal watcher is created, and
423 should be left alone otherwise. This variable determines how often 424 should be left alone otherwise. This variable determines how often
424 AnyEvent polls for signals (in case a wake-up was missed). Higher values 425 AnyEvent polls for signals (in case a wake-up was missed). Higher values
426 saving. 427 saving.
427 428
428 All these problems can be avoided by installing the optional 429 All these problems can be avoided by installing the optional
429 Async::Interrupt module, which works with most event loops. It will not 430 Async::Interrupt module, which works with most event loops. It will not
430 work with inherently broken event loops such as Event or Event::Lib (and 431 work with inherently broken event loops such as Event or Event::Lib (and
431 not with POE currently, as POE does it's own workaround with one-second 432 not with POE currently, as POE does its own workaround with one-second
432 latency). For those, you just have to suffer the delays. 433 latency). For those, you just have to suffer the delays.
433 434
434 CHILD PROCESS WATCHERS 435 CHILD PROCESS WATCHERS
435 $w = AnyEvent->child (pid => <process id>, cb => <callback>); 436 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
436 437
437 You can also watch on a child process exit and catch its exit status. 438 You can also watch for a child process exit and catch its exit status.
438 439
439 The child process is specified by the "pid" argument (one some backends, 440 The child process is specified by the "pid" argument (on some backends,
440 using 0 watches for any child process exit, on others this will croak). 441 using 0 watches for any child process exit, on others this will croak).
441 The watcher will be triggered only when the child process has finished 442 The watcher will be triggered only when the child process has finished
442 and an exit status is available, not on any trace events 443 and an exit status is available, not on any trace events
443 (stopped/continued). 444 (stopped/continued).
444 445
489 $done->recv; 490 $done->recv;
490 491
491 IDLE WATCHERS 492 IDLE WATCHERS
492 $w = AnyEvent->idle (cb => <callback>); 493 $w = AnyEvent->idle (cb => <callback>);
493 494
494 Repeatedly invoke the callback after the process becomes idle, until 495 This will repeatedly invoke the callback after the process becomes idle,
495 either the watcher is destroyed or new events have been detected. 496 until either the watcher is destroyed or new events have been detected.
496 497
497 Idle watchers are useful when there is a need to do something, but it is 498 Idle watchers are useful when there is a need to do something, but it is
498 not so important (or wise) to do it instantly. The callback will be 499 not so important (or wise) to do it instantly. The callback will be
499 invoked only when there is "nothing better to do", which is usually 500 invoked only when there is "nothing better to do", which is usually
500 defined as "all outstanding events have been handled and no new events 501 defined as "all outstanding events have been handled and no new events
570 called when the signal fires. 571 called when the signal fires.
571 572
572 * Condition variables are like "Merge Points" - points in your program 573 * Condition variables are like "Merge Points" - points in your program
573 where you merge multiple independent results/control flows into one. 574 where you merge multiple independent results/control flows into one.
574 575
575 * Condition variables represent a transaction - function that start 576 * Condition variables represent a transaction - functions that start
576 some kind of transaction can return them, leaving the caller the 577 some kind of transaction can return them, leaving the caller the
577 choice between waiting in a blocking fashion, or setting a callback. 578 choice between waiting in a blocking fashion, or setting a callback.
578 579
579 * Condition variables represent future values, or promises to deliver 580 * Condition variables represent future values, or promises to deliver
580 some result, long before the result is available. 581 some result, long before the result is available.
598 599
599 Condition variables are represented by hash refs in perl, and the keys 600 Condition variables are represented by hash refs in perl, and the keys
600 used by AnyEvent itself are all named "_ae_XXX" to make subclassing easy 601 used by AnyEvent itself are all named "_ae_XXX" to make subclassing easy
601 (it is often useful to build your own transaction class on top of 602 (it is often useful to build your own transaction class on top of
602 AnyEvent). To subclass, use "AnyEvent::CondVar" as base class and call 603 AnyEvent). To subclass, use "AnyEvent::CondVar" as base class and call
603 it's "new" method in your own "new" method. 604 its "new" method in your own "new" method.
604 605
605 There are two "sides" to a condition variable - the "producer side" 606 There are two "sides" to a condition variable - the "producer side"
606 which eventually calls "-> send", and the "consumer side", which waits 607 which eventually calls "-> send", and the "consumer side", which waits
607 for the send to occur. 608 for the send to occur.
608 609
668 Condition variables are overloaded so one can call them directly (as 669 Condition variables are overloaded so one can call them directly (as
669 if they were a code reference). Calling them directly is the same as 670 if they were a code reference). Calling them directly is the same as
670 calling "send". 671 calling "send".
671 672
672 $cv->croak ($error) 673 $cv->croak ($error)
673 Similar to send, but causes all call's to "->recv" to invoke 674 Similar to send, but causes all calls to "->recv" to invoke
674 "Carp::croak" with the given error message/object/scalar. 675 "Carp::croak" with the given error message/object/scalar.
675 676
676 This can be used to signal any errors to the condition variable 677 This can be used to signal any errors to the condition variable
677 user/consumer. Doing it this way instead of calling "croak" directly 678 user/consumer. Doing it this way instead of calling "croak" directly
678 delays the error detetcion, but has the overwhelmign advantage that 679 delays the error detection, but has the overwhelming advantage that
679 it diagnoses the error at the place where the result is expected, 680 it diagnoses the error at the place where the result is expected,
680 and not deep in some event clalback without connection to the actual 681 and not deep in some event callback with no connection to the actual
681 code causing the problem. 682 code causing the problem.
682 683
683 $cv->begin ([group callback]) 684 $cv->begin ([group callback])
684 $cv->end 685 $cv->end
685 These two methods can be used to combine many transactions/events 686 These two methods can be used to combine many transactions/events
722 there is one call to "begin", so the condvar waits for all calls to 723 there is one call to "begin", so the condvar waits for all calls to
723 "end" before sending. 724 "end" before sending.
724 725
725 The ping example mentioned above is slightly more complicated, as 726 The ping example mentioned above is slightly more complicated, as
726 the there are results to be passwd back, and the number of tasks 727 the there are results to be passwd back, and the number of tasks
727 that are begung can potentially be zero: 728 that are begun can potentially be zero:
728 729
729 my $cv = AnyEvent->condvar; 730 my $cv = AnyEvent->condvar;
730 731
731 my %result; 732 my %result;
732 $cv->begin (sub { shift->send (\%result) }); 733 $cv->begin (sub { shift->send (\%result) });
753 callback to be called once the counter reaches 0, and second, it 754 callback to be called once the counter reaches 0, and second, it
754 ensures that "send" is called even when "no" hosts are being pinged 755 ensures that "send" is called even when "no" hosts are being pinged
755 (the loop doesn't execute once). 756 (the loop doesn't execute once).
756 757
757 This is the general pattern when you "fan out" into multiple (but 758 This is the general pattern when you "fan out" into multiple (but
758 potentially none) subrequests: use an outer "begin"/"end" pair to 759 potentially zero) subrequests: use an outer "begin"/"end" pair to
759 set the callback and ensure "end" is called at least once, and then, 760 set the callback and ensure "end" is called at least once, and then,
760 for each subrequest you start, call "begin" and for each subrequest 761 for each subrequest you start, call "begin" and for each subrequest
761 you finish, call "end". 762 you finish, call "end".
762 763
763 METHODS FOR CONSUMERS 764 METHODS FOR CONSUMERS
764 These methods should only be used by the consuming side, i.e. the code 765 These methods should only be used by the consuming side, i.e. the code
765 awaits the condition. 766 awaits the condition.
766 767
767 $cv->recv 768 $cv->recv
768 Wait (blocking if necessary) until the "->send" or "->croak" methods 769 Wait (blocking if necessary) until the "->send" or "->croak" methods
769 have been called on c<$cv>, while servicing other watchers normally. 770 have been called on $cv, while servicing other watchers normally.
770 771
771 You can only wait once on a condition - additional calls are valid 772 You can only wait once on a condition - additional calls are valid
772 but will return immediately. 773 but will return immediately.
773 774
774 If an error condition has been set by calling "->croak", then this 775 If an error condition has been set by calling "->croak", then this
791 example, by coupling condition variables with some kind of request 792 example, by coupling condition variables with some kind of request
792 results and supporting callbacks so the caller knows that getting 793 results and supporting callbacks so the caller knows that getting
793 the result will not block, while still supporting blocking waits if 794 the result will not block, while still supporting blocking waits if
794 the caller so desires). 795 the caller so desires).
795 796
796 You can ensure that "-recv" never blocks by setting a callback and 797 You can ensure that "->recv" never blocks by setting a callback and
797 only calling "->recv" from within that callback (or at a later 798 only calling "->recv" from within that callback (or at a later
798 time). This will work even when the event loop does not support 799 time). This will work even when the event loop does not support
799 blocking waits otherwise. 800 blocking waits otherwise.
800 801
801 $bool = $cv->ready 802 $bool = $cv->ready
804 805
805 $cb = $cv->cb ($cb->($cv)) 806 $cb = $cv->cb ($cb->($cv))
806 This is a mutator function that returns the callback set and 807 This is a mutator function that returns the callback set and
807 optionally replaces it before doing so. 808 optionally replaces it before doing so.
808 809
809 The callback will be called when the condition becomes (or already 810 The callback will be called when the condition becomes "true", i.e.
810 was) "true", i.e. when "send" or "croak" are called (or were 811 when "send" or "croak" are called, with the only argument being the
811 called), with the only argument being the condition variable itself. 812 condition variable itself. If the condition is already true, the
812 Calling "recv" inside the callback or at any later time is 813 callback is called immediately when it is set. Calling "recv" inside
813 guaranteed not to block. 814 the callback or at any later time is guaranteed not to block.
814 815
815SUPPORTED EVENT LOOPS/BACKENDS 816SUPPORTED EVENT LOOPS/BACKENDS
816 The available backend classes are (every class has its own manpage): 817 The available backend classes are (every class has its own manpage):
817 818
818 Backends that are autoprobed when no other event loop can be found. 819 Backends that are autoprobed when no other event loop can be found.
823 824
824 AnyEvent::Impl::EV based on EV (interface to libev, best choice). 825 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
825 AnyEvent::Impl::Perl pure-perl implementation, fast and portable. 826 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
826 827
827 Backends that are transparently being picked up when they are used. 828 Backends that are transparently being picked up when they are used.
828 These will be used when they are currently loaded when the first 829 These will be used if they are already loaded when the first watcher
829 watcher is created, in which case it is assumed that the application 830 is created, in which case it is assumed that the application is
830 is using them. This means that AnyEvent will automatically pick the 831 using them. This means that AnyEvent will automatically pick the
831 right backend when the main program loads an event module before 832 right backend when the main program loads an event module before
832 anything starts to create watchers. Nothing special needs to be done 833 anything starts to create watchers. Nothing special needs to be done
833 by the main program. 834 by the main program.
834 835
835 AnyEvent::Impl::Event based on Event, very stable, few glitches. 836 AnyEvent::Impl::Event based on Event, very stable, few glitches.
849 850
850 Support for IO::Async can only be partial, as it is too broken and 851 Support for IO::Async can only be partial, as it is too broken and
851 architecturally limited to even support the AnyEvent API. It also is 852 architecturally limited to even support the AnyEvent API. It also is
852 the only event loop that needs the loop to be set explicitly, so it 853 the only event loop that needs the loop to be set explicitly, so it
853 can only be used by a main program knowing about AnyEvent. See 854 can only be used by a main program knowing about AnyEvent. See
854 AnyEvent::Impl::Async for the gory details. 855 AnyEvent::Impl::IOAsync for the gory details.
855 856
856 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed. 857 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed.
857 858
858 Event loops that are indirectly supported via other backends. 859 Event loops that are indirectly supported via other backends.
859 Some event loops can be supported via other modules: 860 Some event loops can be supported via other modules:
880 Contains "undef" until the first watcher is being created, before 881 Contains "undef" until the first watcher is being created, before
881 the backend has been autodetected. 882 the backend has been autodetected.
882 883
883 Afterwards it contains the event model that is being used, which is 884 Afterwards it contains the event model that is being used, which is
884 the name of the Perl class implementing the model. This class is 885 the name of the Perl class implementing the model. This class is
885 usually one of the "AnyEvent::Impl:xxx" modules, but can be any 886 usually one of the "AnyEvent::Impl::xxx" modules, but can be any
886 other class in the case AnyEvent has been extended at runtime (e.g. 887 other class in the case AnyEvent has been extended at runtime (e.g.
887 in *rxvt-unicode* it will be "urxvt::anyevent"). 888 in *rxvt-unicode* it will be "urxvt::anyevent").
888 889
889 AnyEvent::detect 890 AnyEvent::detect
890 Returns $AnyEvent::MODEL, forcing autodetection of the event model 891 Returns $AnyEvent::MODEL, forcing autodetection of the event model
891 if necessary. You should only call this function right before you 892 if necessary. You should only call this function right before you
892 would have created an AnyEvent watcher anyway, that is, as late as 893 would have created an AnyEvent watcher anyway, that is, as late as
893 possible at runtime, and not e.g. while initialising of your module. 894 possible at runtime, and not e.g. during initialisation of your
895 module.
894 896
895 If you need to do some initialisation before AnyEvent watchers are 897 If you need to do some initialisation before AnyEvent watchers are
896 created, use "post_detect". 898 created, use "post_detect".
897 899
898 $guard = AnyEvent::post_detect { BLOCK } 900 $guard = AnyEvent::post_detect { BLOCK }
899 Arranges for the code block to be executed as soon as the event 901 Arranges for the code block to be executed as soon as the event
900 model is autodetected (or immediately if this has already happened). 902 model is autodetected (or immediately if that has already happened).
901 903
902 The block will be executed *after* the actual backend has been 904 The block will be executed *after* the actual backend has been
903 detected ($AnyEvent::MODEL is set), but *before* any watchers have 905 detected ($AnyEvent::MODEL is set), but *before* any watchers have
904 been created, so it is possible to e.g. patch @AnyEvent::ISA or do 906 been created, so it is possible to e.g. patch @AnyEvent::ISA or do
905 other initialisations - see the sources of AnyEvent::Strict or 907 other initialisations - see the sources of AnyEvent::Strict or
914 object that automatically removes the callback again when it is 916 object that automatically removes the callback again when it is
915 destroyed (or "undef" when the hook was immediately executed). See 917 destroyed (or "undef" when the hook was immediately executed). See
916 AnyEvent::AIO for a case where this is useful. 918 AnyEvent::AIO for a case where this is useful.
917 919
918 Example: Create a watcher for the IO::AIO module and store it in 920 Example: Create a watcher for the IO::AIO module and store it in
919 $WATCHER. Only do so after the event loop is initialised, though. 921 $WATCHER, but do so only do so after the event loop is initialised.
920 922
921 our WATCHER; 923 our WATCHER;
922 924
923 my $guard = AnyEvent::post_detect { 925 my $guard = AnyEvent::post_detect {
924 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb); 926 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
931 933
932 $WATCHER ||= $guard; 934 $WATCHER ||= $guard;
933 935
934 @AnyEvent::post_detect 936 @AnyEvent::post_detect
935 If there are any code references in this array (you can "push" to it 937 If there are any code references in this array (you can "push" to it
936 before or after loading AnyEvent), then they will called directly 938 before or after loading AnyEvent), then they will be called directly
937 after the event loop has been chosen. 939 after the event loop has been chosen.
938 940
939 You should check $AnyEvent::MODEL before adding to this array, 941 You should check $AnyEvent::MODEL before adding to this array,
940 though: if it is defined then the event loop has already been 942 though: if it is defined then the event loop has already been
941 detected, and the array will be ignored. 943 detected, and the array will be ignored.
976 stall the whole program, and the whole point of using events is to stay 978 stall the whole program, and the whole point of using events is to stay
977 interactive. 979 interactive.
978 980
979 It is fine, however, to call "->recv" when the user of your module 981 It is fine, however, to call "->recv" when the user of your module
980 requests it (i.e. if you create a http request object ad have a method 982 requests it (i.e. if you create a http request object ad have a method
981 called "results" that returns the results, it should call "->recv" 983 called "results" that returns the results, it may call "->recv" freely,
982 freely, as the user of your module knows what she is doing. always). 984 as the user of your module knows what she is doing. Always).
983 985
984WHAT TO DO IN THE MAIN PROGRAM 986WHAT TO DO IN THE MAIN PROGRAM
985 There will always be a single main program - the only place that should 987 There will always be a single main program - the only place that should
986 dictate which event model to use. 988 dictate which event model to use.
987 989
988 If it doesn't care, it can just "use AnyEvent" and use it itself, or not 990 If the program is not event-based, it need not do anything special, even
989 do anything special (it does not need to be event-based) and let 991 when it depends on a module that uses an AnyEvent. If the program itself
990 AnyEvent decide which implementation to chose if some module relies on 992 uses AnyEvent, but does not care which event loop is used, all it needs
991 it. 993 to do is "use AnyEvent". In either case, AnyEvent will choose the best
994 available loop implementation.
992 995
993 If the main program relies on a specific event model - for example, in 996 If the main program relies on a specific event model - for example, in
994 Gtk2 programs you have to rely on the Glib module - you should load the 997 Gtk2 programs you have to rely on the Glib module - you should load the
995 event module before loading AnyEvent or any module that uses it: 998 event module before loading AnyEvent or any module that uses it:
996 generally speaking, you should load it as early as possible. The reason 999 generally speaking, you should load it as early as possible. The reason
997 is that modules might create watchers when they are loaded, and AnyEvent 1000 is that modules might create watchers when they are loaded, and AnyEvent
998 will decide on the event model to use as soon as it creates watchers, 1001 will decide on the event model to use as soon as it creates watchers,
999 and it might chose the wrong one unless you load the correct one 1002 and it might choose the wrong one unless you load the correct one
1000 yourself. 1003 yourself.
1001 1004
1002 You can chose to use a pure-perl implementation by loading the 1005 You can chose to use a pure-perl implementation by loading the
1003 "AnyEvent::Impl::Perl" module, which gives you similar behaviour 1006 "AnyEvent::Impl::Perl" module, which gives you similar behaviour
1004 everywhere, but letting AnyEvent chose the model is generally better. 1007 everywhere, but letting AnyEvent chose the model is generally better.
1024 AnyEvent as a client and can therefore be mixed easily with other 1027 AnyEvent as a client and can therefore be mixed easily with other
1025 AnyEvent modules and other event loops in the same program. Some of the 1028 AnyEvent modules and other event loops in the same program. Some of the
1026 modules come as part of AnyEvent, the others are available via CPAN. 1029 modules come as part of AnyEvent, the others are available via CPAN.
1027 1030
1028 AnyEvent::Util 1031 AnyEvent::Util
1029 Contains various utility functions that replace often-used but 1032 Contains various utility functions that replace often-used blocking
1030 blocking functions such as "inet_aton" by event-/callback-based 1033 functions such as "inet_aton" with event/callback-based versions.
1031 versions.
1032 1034
1033 AnyEvent::Socket 1035 AnyEvent::Socket
1034 Provides various utility functions for (internet protocol) sockets, 1036 Provides various utility functions for (internet protocol) sockets,
1035 addresses and name resolution. Also functions to create non-blocking 1037 addresses and name resolution. Also functions to create non-blocking
1036 tcp connections or tcp servers, with IPv6 and SRV record support and 1038 tcp connections or tcp servers, with IPv6 and SRV record support and
1037 more. 1039 more.
1038 1040
1039 AnyEvent::Handle 1041 AnyEvent::Handle
1040 Provide read and write buffers, manages watchers for reads and 1042 Provide read and write buffers, manages watchers for reads and
1041 writes, supports raw and formatted I/O, I/O queued and fully 1043 writes, supports raw and formatted I/O, I/O queued and fully
1042 transparent and non-blocking SSL/TLS (via AnyEvent::TLS. 1044 transparent and non-blocking SSL/TLS (via AnyEvent::TLS).
1043 1045
1044 AnyEvent::DNS 1046 AnyEvent::DNS
1045 Provides rich asynchronous DNS resolver capabilities. 1047 Provides rich asynchronous DNS resolver capabilities.
1046 1048
1047 AnyEvent::HTTP, AnyEvent::IRC, AnyEvent::XMPP, AnyEvent::GPSD, 1049 AnyEvent::HTTP, AnyEvent::IRC, AnyEvent::XMPP, AnyEvent::GPSD,
1053 AnyEvent::Handle::UDP 1055 AnyEvent::Handle::UDP
1054 Here be danger! 1056 Here be danger!
1055 1057
1056 As Pauli would put it, "Not only is it not right, it's not even 1058 As Pauli would put it, "Not only is it not right, it's not even
1057 wrong!" - there are so many things wrong with AnyEvent::Handle::UDP, 1059 wrong!" - there are so many things wrong with AnyEvent::Handle::UDP,
1058 most notably it's use of a stream-based API with a protocol that 1060 most notably its use of a stream-based API with a protocol that
1059 isn't streamable, that the only way to improve it is to delete it. 1061 isn't streamable, that the only way to improve it is to delete it.
1060 1062
1061 It features data corruption (but typically only under load) and 1063 It features data corruption (but typically only under load) and
1062 general confusion. On top, the author is not only clueless about UDP 1064 general confusion. On top, the author is not only clueless about UDP
1063 but also fact-resistant - some gems of his understanding: "connect 1065 but also fact-resistant - some gems of his understanding: "connect
1067 doesn't even understand what's wrong with his module when it is 1069 doesn't even understand what's wrong with his module when it is
1068 explained to him. 1070 explained to him.
1069 1071
1070 AnyEvent::DBI 1072 AnyEvent::DBI
1071 Executes DBI requests asynchronously in a proxy process for you, 1073 Executes DBI requests asynchronously in a proxy process for you,
1072 notifying you in an event-bnased way when the operation is finished. 1074 notifying you in an event-based way when the operation is finished.
1073 1075
1074 AnyEvent::AIO 1076 AnyEvent::AIO
1075 Truly asynchronous (as opposed to non-blocking) I/O, should be in 1077 Truly asynchronous (as opposed to non-blocking) I/O, should be in
1076 the toolbox of every event programmer. AnyEvent::AIO transparently 1078 the toolbox of every event programmer. AnyEvent::AIO transparently
1077 fuses IO::AIO and AnyEvent together, giving AnyEvent access to 1079 fuses IO::AIO and AnyEvent together, giving AnyEvent access to
1140 thoroughly check the arguments passed to most method calls. If it 1142 thoroughly check the arguments passed to most method calls. If it
1141 finds any problems, it will croak. 1143 finds any problems, it will croak.
1142 1144
1143 In other words, enables "strict" mode. 1145 In other words, enables "strict" mode.
1144 1146
1145 Unlike "use strict" (or it's modern cousin, "use common::sense", it 1147 Unlike "use strict" (or its modern cousin, "use common::sense", it
1146 is definitely recommended to keep it off in production. Keeping 1148 is definitely recommended to keep it off in production. Keeping
1147 "PERL_ANYEVENT_STRICT=1" in your environment while developing 1149 "PERL_ANYEVENT_STRICT=1" in your environment while developing
1148 programs can be very useful, however. 1150 programs can be very useful, however.
1149 1151
1150 "PERL_ANYEVENT_MODEL" 1152 "PERL_ANYEVENT_MODEL"
1746 1748
1747 Feel free to install your own handler, or reset it to defaults. 1749 Feel free to install your own handler, or reset it to defaults.
1748 1750
1749RECOMMENDED/OPTIONAL MODULES 1751RECOMMENDED/OPTIONAL MODULES
1750 One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and 1752 One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
1751 it's built-in modules) are required to use it. 1753 its built-in modules) are required to use it.
1752 1754
1753 That does not mean that AnyEvent won't take advantage of some additional 1755 That does not mean that AnyEvent won't take advantage of some additional
1754 modules if they are installed. 1756 modules if they are installed.
1755 1757
1756 This section explains which additional modules will be used, and how 1758 This section explains which additional modules will be used, and how
1807 worthwhile: If this module is installed, then AnyEvent::Handle (with 1809 worthwhile: If this module is installed, then AnyEvent::Handle (with
1808 the help of AnyEvent::TLS), gains the ability to do TLS/SSL. 1810 the help of AnyEvent::TLS), gains the ability to do TLS/SSL.
1809 1811
1810 Time::HiRes 1812 Time::HiRes
1811 This module is part of perl since release 5.008. It will be used 1813 This module is part of perl since release 5.008. It will be used
1812 when the chosen event library does not come with a timing source on 1814 when the chosen event library does not come with a timing source of
1813 it's own. The pure-perl event loop (AnyEvent::Impl::Perl) will 1815 its own. The pure-perl event loop (AnyEvent::Impl::Perl) will
1814 additionally use it to try to use a monotonic clock for timing 1816 additionally use it to try to use a monotonic clock for timing
1815 stability. 1817 stability.
1816 1818
1817FORK 1819FORK
1818 Most event libraries are not fork-safe. The ones who are usually are 1820 Most event libraries are not fork-safe. The ones who are usually are
1871 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other 1873 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
1872 annoying memleaks, such as leaking on "map" and "grep" but it is usually 1874 annoying memleaks, such as leaking on "map" and "grep" but it is usually
1873 not as pronounced). 1875 not as pronounced).
1874 1876
1875SEE ALSO 1877SEE ALSO
1878 Tutorial/Introduction: AnyEvent::Intro.
1879
1880 FAQ: AnyEvent::FAQ.
1881
1876 Utility functions: AnyEvent::Util. 1882 Utility functions: AnyEvent::Util.
1877 1883
1878 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, 1884 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
1879 Event::Lib, Qt, POE. 1885 Event::Lib, Qt, POE.
1880 1886
1886 Non-blocking file handles, sockets, TCP clients and servers: 1892 Non-blocking file handles, sockets, TCP clients and servers:
1887 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS. 1893 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1888 1894
1889 Asynchronous DNS: AnyEvent::DNS. 1895 Asynchronous DNS: AnyEvent::DNS.
1890 1896
1891 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, 1897 Thread support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event.
1892 1898
1893 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::XMPP, 1899 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::IRC,
1894 AnyEvent::HTTP. 1900 AnyEvent::HTTP.
1895 1901
1896AUTHOR 1902AUTHOR
1897 Marc Lehmann <schmorp@schmorp.de> 1903 Marc Lehmann <schmorp@schmorp.de>
1898 http://home.schmorp.de/ 1904 http://home.schmorp.de/

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines