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.66 by root, Sun Aug 21 03:02:32 2011 UTC

1NAME 1NAME
2 AnyEvent - the DBI of event loop programming 2 AnyEvent - the DBI of event loop programming
3 3
4 EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, 4 EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async,
5 Qt and POE are various supported event loops/environments. 5 Qt, FLTK and POE are various supported event loops/environments.
6 6
7SYNOPSIS 7SYNOPSIS
8 use AnyEvent; 8 use AnyEvent;
9 9
10 # if you prefer function calls, look at the AE manpage for 10 # if you prefer function calls, look at the AE manpage for
… …
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 + EV? No go. Tk + Event? No go. Again: if your module
84 module uses one of those, every user of your module has to use it, too. 86 uses one of those, every user of your module has to use it, too. But if
85 But if your module uses AnyEvent, it works transparently with all event 87 your module uses AnyEvent, it works transparently with all event models
86 models it supports (including stuff like IO::Async, as long as those use 88 it supports (including stuff like IO::Async, as long as those use one of
87 one of the supported event loops. It is trivial to add new event loops 89 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::Loop, Event, Glib,
119 AnyEvent::Impl::Perl, Tk, Event::Lib, Qt, POE. The first one found is 121 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::Loop should always work, so the other two are not normally
123 successfully loaded will be used. If, after this, still none could be 125 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 "AnyEvent::Loop".
141 "AnyEvent::Impl::Perl". Like other event modules you can load it 142 Like other event modules you can load it explicitly and enjoy the high
142 explicitly and enjoy the high availability of that event loop :) 143 availability of that event loop :)
143 144
144WATCHERS 145WATCHERS
145 AnyEvent has the central concept of a *watcher*, which is an object that 146 AnyEvent has the central concept of a *watcher*, which is an object that
146 stores relevant data for each kind of event you are waiting for, such as 147 stores relevant data for each kind of event you are waiting for, such as
147 the callback to call, the file handle to watch, etc. 148 the callback to call, the file handle to watch, etc.
… …
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
… …
346 can get whatever behaviour you want with any event loop, by taking 347 can get whatever behaviour you want with any event loop, by taking
347 the difference between "AnyEvent->time" and "AnyEvent->now" into 348 the difference between "AnyEvent->time" and "AnyEvent->now" into
348 account. 349 account.
349 350
350 AnyEvent->now_update 351 AnyEvent->now_update
351 Some event loops (such as EV or AnyEvent::Impl::Perl) cache the 352 Some event loops (such as EV or AnyEvent::Loop) cache the current
352 current time for each loop iteration (see the discussion of 353 time for each loop iteration (see the discussion of AnyEvent->now,
353 AnyEvent->now, above). 354 above).
354 355
355 When a callback runs for a long time (or when the process sleeps), 356 When a callback runs for a long time (or when the process sleeps),
356 then this "current" time will differ substantially from the real 357 then this "current" time will differ substantially from the real
357 time, which might affect timers and time-outs. 358 time, which might affect timers and time-outs.
358 359
… …
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
… …
465 This means you cannot create a child watcher as the very first thing in 466 This means you cannot create a child watcher as the very first thing in
466 an AnyEvent program, you *have* to create at least one watcher before 467 an AnyEvent program, you *have* to create at least one watcher before
467 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 468 you "fork" the child (alternatively, you can call "AnyEvent::detect").
468 469
469 As most event loops do not support waiting for child events, they will 470 As most event loops do not support waiting for child events, they will
470 be emulated by AnyEvent in most cases, in which the latency and race 471 be emulated by AnyEvent in most cases, in which case the latency and
471 problems mentioned in the description of signal watchers apply. 472 race problems mentioned in the description of signal watchers apply.
472 473
473 Example: fork a process and wait for it 474 Example: fork a process and wait for it
474 475
475 my $done = AnyEvent->condvar; 476 my $done = AnyEvent->condvar;
476 477
… …
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.
… …
820 use. If EV is not installed, then AnyEvent will fall back to its own 821 use. If EV is not installed, then AnyEvent will fall back to its own
821 pure-perl implementation, which is available everywhere as it comes 822 pure-perl implementation, which is available everywhere as it comes
822 with AnyEvent itself. 823 with AnyEvent itself.
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 AnyEvent::Loop, 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.
836 AnyEvent::Impl::Glib based on Glib, slow but very stable. 837 AnyEvent::Impl::Glib based on Glib, slow but very stable.
837 AnyEvent::Impl::Tk based on Tk, very broken. 838 AnyEvent::Impl::Tk based on Tk, very broken.
838 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 839 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
839 AnyEvent::Impl::POE based on POE, very slow, some limitations. 840 AnyEvent::Impl::POE based on POE, very slow, some limitations.
840 AnyEvent::Impl::Irssi used when running within irssi. 841 AnyEvent::Impl::Irssi used when running within irssi.
842 AnyEvent::Impl::IOAsync based on IO::Async.
843 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop.
844 AnyEvent::Impl::FLTK2 based on FLTK (fltk 2 binding).
841 845
842 Backends with special needs. 846 Backends with special needs.
843 Qt requires the Qt::Application to be instantiated first, but will 847 Qt requires the Qt::Application to be instantiated first, but will
844 otherwise be picked up automatically. As long as the main program 848 otherwise be picked up automatically. As long as the main program
845 instantiates the application before any AnyEvent watchers are 849 instantiates the application before any AnyEvent watchers are
846 created, everything should just work. 850 created, everything should just work.
847 851
848 AnyEvent::Impl::Qt based on Qt. 852 AnyEvent::Impl::Qt based on Qt.
849 853
850 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 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 AnyEvent::Impl::Async for the gory details.
855
856 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed.
857
858 Event loops that are indirectly supported via other backends. 854 Event loops that are indirectly supported via other backends.
859 Some event loops can be supported via other modules: 855 Some event loops can be supported via other modules:
860 856
861 There is no direct support for WxWidgets (Wx) or Prima. 857 There is no direct support for WxWidgets (Wx) or Prima.
862 858
… …
880 Contains "undef" until the first watcher is being created, before 876 Contains "undef" until the first watcher is being created, before
881 the backend has been autodetected. 877 the backend has been autodetected.
882 878
883 Afterwards it contains the event model that is being used, which is 879 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 880 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 881 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. 882 other class in the case AnyEvent has been extended at runtime (e.g.
887 in *rxvt-unicode* it will be "urxvt::anyevent"). 883 in *rxvt-unicode* it will be "urxvt::anyevent").
888 884
889 AnyEvent::detect 885 AnyEvent::detect
890 Returns $AnyEvent::MODEL, forcing autodetection of the event model 886 Returns $AnyEvent::MODEL, forcing autodetection of the event model
891 if necessary. You should only call this function right before you 887 if necessary. You should only call this function right before you
892 would have created an AnyEvent watcher anyway, that is, as late as 888 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. 889 possible at runtime, and not e.g. during initialisation of your
890 module.
891
892 The effect of calling this function is as if a watcher had been
893 created (specifically, actions that happen "when the first watcher
894 is created" happen when calling detetc as well).
894 895
895 If you need to do some initialisation before AnyEvent watchers are 896 If you need to do some initialisation before AnyEvent watchers are
896 created, use "post_detect". 897 created, use "post_detect".
897 898
898 $guard = AnyEvent::post_detect { BLOCK } 899 $guard = AnyEvent::post_detect { BLOCK }
899 Arranges for the code block to be executed as soon as the event 900 Arranges for the code block to be executed as soon as the event
900 model is autodetected (or immediately if this has already happened). 901 model is autodetected (or immediately if that has already happened).
901 902
902 The block will be executed *after* the actual backend has been 903 The block will be executed *after* the actual backend has been
903 detected ($AnyEvent::MODEL is set), but *before* any watchers have 904 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 905 been created, so it is possible to e.g. patch @AnyEvent::ISA or do
905 other initialisations - see the sources of AnyEvent::Strict or 906 other initialisations - see the sources of AnyEvent::Strict or
… …
914 object that automatically removes the callback again when it is 915 object that automatically removes the callback again when it is
915 destroyed (or "undef" when the hook was immediately executed). See 916 destroyed (or "undef" when the hook was immediately executed). See
916 AnyEvent::AIO for a case where this is useful. 917 AnyEvent::AIO for a case where this is useful.
917 918
918 Example: Create a watcher for the IO::AIO module and store it in 919 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. 920 $WATCHER, but do so only do so after the event loop is initialised.
920 921
921 our WATCHER; 922 our WATCHER;
922 923
923 my $guard = AnyEvent::post_detect { 924 my $guard = AnyEvent::post_detect {
924 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb); 925 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
… …
931 932
932 $WATCHER ||= $guard; 933 $WATCHER ||= $guard;
933 934
934 @AnyEvent::post_detect 935 @AnyEvent::post_detect
935 If there are any code references in this array (you can "push" to it 936 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 937 before or after loading AnyEvent), then they will be called directly
937 after the event loop has been chosen. 938 after the event loop has been chosen.
938 939
939 You should check $AnyEvent::MODEL before adding to this array, 940 You should check $AnyEvent::MODEL before adding to this array,
940 though: if it is defined then the event loop has already been 941 though: if it is defined then the event loop has already been
941 detected, and the array will be ignored. 942 detected, and the array will be ignored.
… …
960 # AnyEvent not yet initialised, so make sure to load Coro::AnyEvent 961 # AnyEvent not yet initialised, so make sure to load Coro::AnyEvent
961 # as soon as it is 962 # as soon as it is
962 push @AnyEvent::post_detect, sub { require Coro::AnyEvent }; 963 push @AnyEvent::post_detect, sub { require Coro::AnyEvent };
963 } 964 }
964 965
966 AnyEvent::postpone { BLOCK }
967 Arranges for the block to be executed as soon as possible, but not
968 before the call itself returns. In practise, the block will be
969 executed just before the event loop polls for new events, or shortly
970 afterwards.
971
972 This function never returns anything (to make the "return postpone {
973 ... }" idiom more useful.
974
975 To understand the usefulness of this function, consider a function
976 that asynchronously does something for you and returns some
977 transaction object or guard to let you cancel the operation. For
978 example, "AnyEvent::Socket::tcp_connect":
979
980 # start a conenction attempt unless one is active
981 $self->{connect_guard} ||= AnyEvent::Socket::tcp_connect "www.example.net", 80, sub {
982 delete $self->{connect_guard};
983 ...
984 };
985
986 Imagine that this function could instantly call the callback, for
987 example, because it detects an obvious error such as a negative port
988 number. Invoking the callback before the function returns causes
989 problems however: the callback will be called and will try to delete
990 the guard object. But since the function hasn't returned yet, there
991 is nothing to delete. When the function eventually returns it will
992 assign the guard object to "$self->{connect_guard}", where it will
993 likely never be deleted, so the program thinks it is still trying to
994 connect.
995
996 This is where "AnyEvent::postpone" should be used. Instead of
997 calling the callback directly on error:
998
999 $cb->(undef), return # signal error to callback, BAD!
1000 if $some_error_condition;
1001
1002 It should use "postpone":
1003
1004 AnyEvent::postpone { $cb->(undef) }, return # signal error to callback, later
1005 if $some_error_condition;
1006
1007 AnyEvent::log $level, $msg[, @args]
1008 Log the given $msg at the given $level.
1009
1010 Loads AnyEvent::Log on first use and calls "AnyEvent::Log::log" -
1011 consequently, look at the AnyEvent::Log documentation for details.
1012
1013 If you want to sprinkle loads of logging calls around your code,
1014 consider creating a logger callback with the "AnyEvent::Log::logger"
1015 function.
1016
965WHAT TO DO IN A MODULE 1017WHAT TO DO IN A MODULE
966 As a module author, you should "use AnyEvent" and call AnyEvent methods 1018 As a module author, you should "use AnyEvent" and call AnyEvent methods
967 freely, but you should not load a specific event module or rely on it. 1019 freely, but you should not load a specific event module or rely on it.
968 1020
969 Be careful when you create watchers in the module body - AnyEvent will 1021 Be careful when you create watchers in the module body - AnyEvent will
… …
976 stall the whole program, and the whole point of using events is to stay 1028 stall the whole program, and the whole point of using events is to stay
977 interactive. 1029 interactive.
978 1030
979 It is fine, however, to call "->recv" when the user of your module 1031 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 1032 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" 1033 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). 1034 as the user of your module knows what she is doing. Always).
983 1035
984WHAT TO DO IN THE MAIN PROGRAM 1036WHAT TO DO IN THE MAIN PROGRAM
985 There will always be a single main program - the only place that should 1037 There will always be a single main program - the only place that should
986 dictate which event model to use. 1038 dictate which event model to use.
987 1039
988 If it doesn't care, it can just "use AnyEvent" and use it itself, or not 1040 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 1041 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 1042 uses AnyEvent, but does not care which event loop is used, all it needs
991 it. 1043 to do is "use AnyEvent". In either case, AnyEvent will choose the best
1044 available loop implementation.
992 1045
993 If the main program relies on a specific event model - for example, in 1046 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 1047 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: 1048 event module before loading AnyEvent or any module that uses it:
996 generally speaking, you should load it as early as possible. The reason 1049 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 1050 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, 1051 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 1052 and it might choose the wrong one unless you load the correct one
1000 yourself. 1053 yourself.
1001 1054
1002 You can chose to use a pure-perl implementation by loading the 1055 You can chose to use a pure-perl implementation by loading the
1003 "AnyEvent::Impl::Perl" module, which gives you similar behaviour 1056 "AnyEvent::Loop" module, which gives you similar behaviour everywhere,
1004 everywhere, but letting AnyEvent chose the model is generally better. 1057 but letting AnyEvent chose the model is generally better.
1005 1058
1006 MAINLOOP EMULATION 1059 MAINLOOP EMULATION
1007 Sometimes (often for short test scripts, or even standalone programs who 1060 Sometimes (often for short test scripts, or even standalone programs who
1008 only want to use AnyEvent), you do not want to run a specific event 1061 only want to use AnyEvent), you do not want to run a specific event
1009 loop. 1062 loop.
… …
1021 1074
1022OTHER MODULES 1075OTHER MODULES
1023 The following is a non-exhaustive list of additional modules that use 1076 The following is a non-exhaustive list of additional modules that use
1024 AnyEvent as a client and can therefore be mixed easily with other 1077 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 1078 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. 1079 modules come as part of AnyEvent, the others are available via CPAN (see
1080 <http://search.cpan.org/search?m=module&q=anyevent%3A%3A*> for a longer
1081 non-exhaustive list), and the list is heavily biased towards modules of
1082 the AnyEvent author himself :)
1027 1083
1028 AnyEvent::Util 1084 AnyEvent::Util
1029 Contains various utility functions that replace often-used but 1085 Contains various utility functions that replace often-used blocking
1030 blocking functions such as "inet_aton" by event-/callback-based 1086 functions such as "inet_aton" with event/callback-based versions.
1031 versions.
1032 1087
1033 AnyEvent::Socket 1088 AnyEvent::Socket
1034 Provides various utility functions for (internet protocol) sockets, 1089 Provides various utility functions for (internet protocol) sockets,
1035 addresses and name resolution. Also functions to create non-blocking 1090 addresses and name resolution. Also functions to create non-blocking
1036 tcp connections or tcp servers, with IPv6 and SRV record support and 1091 tcp connections or tcp servers, with IPv6 and SRV record support and
1037 more. 1092 more.
1038 1093
1039 AnyEvent::Handle 1094 AnyEvent::Handle
1040 Provide read and write buffers, manages watchers for reads and 1095 Provide read and write buffers, manages watchers for reads and
1041 writes, supports raw and formatted I/O, I/O queued and fully 1096 writes, supports raw and formatted I/O, I/O queued and fully
1042 transparent and non-blocking SSL/TLS (via AnyEvent::TLS. 1097 transparent and non-blocking SSL/TLS (via AnyEvent::TLS).
1043 1098
1044 AnyEvent::DNS 1099 AnyEvent::DNS
1045 Provides rich asynchronous DNS resolver capabilities. 1100 Provides rich asynchronous DNS resolver capabilities.
1046 1101
1047 AnyEvent::HTTP, AnyEvent::IRC, AnyEvent::XMPP, AnyEvent::GPSD, 1102 AnyEvent::HTTP, AnyEvent::IRC, AnyEvent::XMPP, AnyEvent::GPSD,
… …
1053 AnyEvent::Handle::UDP 1108 AnyEvent::Handle::UDP
1054 Here be danger! 1109 Here be danger!
1055 1110
1056 As Pauli would put it, "Not only is it not right, it's not even 1111 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, 1112 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 1113 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. 1114 isn't streamable, that the only way to improve it is to delete it.
1060 1115
1061 It features data corruption (but typically only under load) and 1116 It features data corruption (but typically only under load) and
1062 general confusion. On top, the author is not only clueless about UDP 1117 general confusion. On top, the author is not only clueless about UDP
1063 but also fact-resistant - some gems of his understanding: "connect 1118 but also fact-resistant - some gems of his understanding: "connect
… …
1067 doesn't even understand what's wrong with his module when it is 1122 doesn't even understand what's wrong with his module when it is
1068 explained to him. 1123 explained to him.
1069 1124
1070 AnyEvent::DBI 1125 AnyEvent::DBI
1071 Executes DBI requests asynchronously in a proxy process for you, 1126 Executes DBI requests asynchronously in a proxy process for you,
1072 notifying you in an event-bnased way when the operation is finished. 1127 notifying you in an event-based way when the operation is finished.
1073 1128
1074 AnyEvent::AIO 1129 AnyEvent::AIO
1075 Truly asynchronous (as opposed to non-blocking) I/O, should be in 1130 Truly asynchronous (as opposed to non-blocking) I/O, should be in
1076 the toolbox of every event programmer. AnyEvent::AIO transparently 1131 the toolbox of every event programmer. AnyEvent::AIO transparently
1077 fuses IO::AIO and AnyEvent together, giving AnyEvent access to 1132 fuses IO::AIO and AnyEvent together, giving AnyEvent access to
… …
1120 "PERL_ANYEVENT_VERBOSE" 1175 "PERL_ANYEVENT_VERBOSE"
1121 By default, AnyEvent will be completely silent except in fatal 1176 By default, AnyEvent will be completely silent except in fatal
1122 conditions. You can set this environment variable to make AnyEvent 1177 conditions. You can set this environment variable to make AnyEvent
1123 more talkative. 1178 more talkative.
1124 1179
1125 When set to 1 or higher, causes AnyEvent to warn about unexpected 1180 When set to 5 or higher, causes AnyEvent to warn about unexpected
1126 conditions, such as not being able to load the event model specified 1181 conditions, such as not being able to load the event model specified
1127 by "PERL_ANYEVENT_MODEL". 1182 by "PERL_ANYEVENT_MODEL".
1128 1183
1129 When set to 2 or higher, cause AnyEvent to report to STDERR which 1184 When set to 7 or higher, cause AnyEvent to report to STDERR which
1130 event model it chooses. 1185 event model it chooses.
1131 1186
1132 When set to 8 or higher, then AnyEvent will report extra information 1187 When set to 8 or higher, then AnyEvent will report extra information
1133 on which optional modules it loads and how it implements certain 1188 on which optional modules it loads and how it implements certain
1134 features. 1189 features.
… …
1140 thoroughly check the arguments passed to most method calls. If it 1195 thoroughly check the arguments passed to most method calls. If it
1141 finds any problems, it will croak. 1196 finds any problems, it will croak.
1142 1197
1143 In other words, enables "strict" mode. 1198 In other words, enables "strict" mode.
1144 1199
1145 Unlike "use strict" (or it's modern cousin, "use common::sense", it 1200 Unlike "use strict" (or its modern cousin, "use common::sense", it
1146 is definitely recommended to keep it off in production. Keeping 1201 is definitely recommended to keep it off in production. Keeping
1147 "PERL_ANYEVENT_STRICT=1" in your environment while developing 1202 "PERL_ANYEVENT_STRICT=1" in your environment while developing
1148 programs can be very useful, however. 1203 programs can be very useful, however.
1149 1204
1205 "PERL_ANYEVENT_DEBUG_SHELL"
1206 If this env variable is set, then its contents will be interpreted
1207 by "AnyEvent::Socket::parse_hostport" (after replacing every
1208 occurance of $$ by the process pid) and an "AnyEvent::Debug::shell"
1209 is bound on that port. The shell object is saved in
1210 $AnyEvent::Debug::SHELL.
1211
1212 This takes place when the first watcher is created.
1213
1214 For example, to bind a debug shell on a unix domain socket in
1215 /tmp/debug<pid>.sock, you could use this:
1216
1217 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
1218
1219 Note that creating sockets in /tmp is very unsafe on multiuser
1220 systems.
1221
1222 "PERL_ANYEVENT_DEBUG_WRAP"
1223 Can be set to 0, 1 or 2 and enables wrapping of all watchers for
1224 debugging purposes. See "AnyEvent::Debug::wrap" for details.
1225
1150 "PERL_ANYEVENT_MODEL" 1226 "PERL_ANYEVENT_MODEL"
1151 This can be used to specify the event model to be used by AnyEvent, 1227 This can be used to specify the event model to be used by AnyEvent,
1152 before auto detection and -probing kicks in. It must be a string 1228 before auto detection and -probing kicks in.
1153 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 1229
1154 gets prepended and the resulting module name is loaded and if the 1230 It normally is a string consisting entirely of ASCII letters (e.g.
1155 load was successful, used as event model. If it fails to load 1231 "EV" or "IOAsync"). The string "AnyEvent::Impl::" gets prepended and
1232 the resulting module name is loaded and - if the load was successful
1233 - used as event model backend. If it fails to load then AnyEvent
1156 AnyEvent will proceed with auto detection and -probing. 1234 will proceed with auto detection and -probing.
1157 1235
1158 This functionality might change in future versions. 1236 If the string ends with "::" instead (e.g. "AnyEvent::Impl::EV::")
1237 then nothing gets prepended and the module name is used as-is (hint:
1238 "::" at the end of a string designates a module name and quotes it
1239 appropriately).
1159 1240
1160 For example, to force the pure perl model (AnyEvent::Impl::Perl) you 1241 For example, to force the pure perl model (AnyEvent::Loop::Perl) you
1161 could start your program like this: 1242 could start your program like this:
1162 1243
1163 PERL_ANYEVENT_MODEL=Perl perl ... 1244 PERL_ANYEVENT_MODEL=Perl perl ...
1164 1245
1165 "PERL_ANYEVENT_PROTOCOLS" 1246 "PERL_ANYEVENT_PROTOCOLS"
… …
1538 when used without AnyEvent), but most event loops have acceptable 1619 when used without AnyEvent), but most event loops have acceptable
1539 performance with or without AnyEvent. 1620 performance with or without AnyEvent.
1540 1621
1541 * The overhead AnyEvent adds is usually much smaller than the overhead 1622 * The overhead AnyEvent adds is usually much smaller than the overhead
1542 of the actual event loop, only with extremely fast event loops such 1623 of the actual event loop, only with extremely fast event loops such
1543 as EV adds AnyEvent significant overhead. 1624 as EV does AnyEvent add significant overhead.
1544 1625
1545 * You should avoid POE like the plague if you want performance or 1626 * You should avoid POE like the plague if you want performance or
1546 reasonable memory usage. 1627 reasonable memory usage.
1547 1628
1548 BENCHMARKING THE LARGE SERVER CASE 1629 BENCHMARKING THE LARGE SERVER CASE
… …
1746 1827
1747 Feel free to install your own handler, or reset it to defaults. 1828 Feel free to install your own handler, or reset it to defaults.
1748 1829
1749RECOMMENDED/OPTIONAL MODULES 1830RECOMMENDED/OPTIONAL MODULES
1750 One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and 1831 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. 1832 its built-in modules) are required to use it.
1752 1833
1753 That does not mean that AnyEvent won't take advantage of some additional 1834 That does not mean that AnyEvent won't take advantage of some additional
1754 modules if they are installed. 1835 modules if they are installed.
1755 1836
1756 This section explains which additional modules will be used, and how 1837 This section explains which additional modules will be used, and how
… …
1807 worthwhile: If this module is installed, then AnyEvent::Handle (with 1888 worthwhile: If this module is installed, then AnyEvent::Handle (with
1808 the help of AnyEvent::TLS), gains the ability to do TLS/SSL. 1889 the help of AnyEvent::TLS), gains the ability to do TLS/SSL.
1809 1890
1810 Time::HiRes 1891 Time::HiRes
1811 This module is part of perl since release 5.008. It will be used 1892 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 1893 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 1894 its own. The pure-perl event loop (AnyEvent::Loop) will additionally
1814 additionally use it to try to use a monotonic clock for timing 1895 load it to try to use a monotonic clock for timing stability.
1815 stability.
1816 1896
1817FORK 1897FORK
1818 Most event libraries are not fork-safe. The ones who are usually are 1898 Most event libraries are not fork-safe. The ones who are usually are
1819 because they rely on inefficient but fork-safe "select" or "poll" calls 1899 because they rely on inefficient but fork-safe "select" or "poll" calls
1820 - higher performance APIs such as BSD's kqueue or the dreaded Linux 1900 - higher performance APIs such as BSD's kqueue or the dreaded Linux
… …
1871 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other 1951 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 1952 annoying memleaks, such as leaking on "map" and "grep" but it is usually
1873 not as pronounced). 1953 not as pronounced).
1874 1954
1875SEE ALSO 1955SEE ALSO
1876 Utility functions: AnyEvent::Util. 1956 Tutorial/Introduction: AnyEvent::Intro.
1877 1957
1878 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, 1958 FAQ: AnyEvent::FAQ.
1879 Event::Lib, Qt, POE. 1959
1960 Utility functions: AnyEvent::Util (misc. grab-bag), AnyEvent::Log
1961 (simply logging).
1962
1963 Development/Debugging: AnyEvent::Strict (stricter checking),
1964 AnyEvent::Debug (interactive shell, watcher tracing).
1965
1966 Supported event modules: AnyEvent::Loop, EV, EV::Glib, Glib::EV, Event,
1967 Glib::Event, Glib, Tk, Event::Lib, Qt, POE, FLTK.
1880 1968
1881 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, 1969 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1882 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, 1970 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1883 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE, 1971 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
1884 AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi. 1972 AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi, AnyEvent::Impl::FLTK.
1885 1973
1886 Non-blocking file handles, sockets, TCP clients and servers: 1974 Non-blocking handles, pipes, stream sockets, TCP clients and servers:
1887 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS. 1975 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1888 1976
1889 Asynchronous DNS: AnyEvent::DNS. 1977 Asynchronous DNS: AnyEvent::DNS.
1890 1978
1891 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, 1979 Thread support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event.
1892 1980
1893 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::XMPP, 1981 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::IRC,
1894 AnyEvent::HTTP. 1982 AnyEvent::HTTP.
1895 1983
1896AUTHOR 1984AUTHOR
1897 Marc Lehmann <schmorp@schmorp.de> 1985 Marc Lehmann <schmorp@schmorp.de>
1898 http://home.schmorp.de/ 1986 http://home.schmorp.de/

Diff Legend

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