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

Comparing AnyEvent/README (file contents):
Revision 1.19 by root, Mon Apr 28 08:02:14 2008 UTC vs.
Revision 1.23 by root, Mon May 26 06:04:38 2008 UTC

1NAME 1=> NAME
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - provide framework for multiple event loops
3 3
4 EV, Event, Coro::EV, Coro::Event, Glib, Tk, Perl, Event::Lib, Qt, POE - 4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event
5 various supported event loops 5 loops
6 6
7SYNOPSIS 7SYNOPSIS
8 use AnyEvent; 8 use AnyEvent;
9 9
10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { 10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub {
… …
14 my $w = AnyEvent->timer (after => $seconds, cb => sub { 14 my $w = AnyEvent->timer (after => $seconds, cb => sub {
15 ... 15 ...
16 }); 16 });
17 17
18 my $w = AnyEvent->condvar; # stores whether a condition was flagged 18 my $w = AnyEvent->condvar; # stores whether a condition was flagged
19 $w->send; # wake up current and all future recv's
19 $w->wait; # enters "main loop" till $condvar gets ->broadcast 20 $w->recv; # enters "main loop" till $condvar gets ->send
20 $w->broadcast; # wake up current and all future wait's
21 21
22WHY YOU SHOULD USE THIS MODULE (OR NOT) 22WHY YOU SHOULD USE THIS MODULE (OR NOT)
23 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 23 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
24 nowadays. So what is different about AnyEvent? 24 nowadays. So what is different about AnyEvent?
25 25
… …
55 those use one of the supported event loops. It is trivial to add new 55 those use one of the supported event loops. It is trivial to add new
56 event loops to AnyEvent, too, so it is future-proof). 56 event loops to AnyEvent, too, so it is future-proof).
57 57
58 In addition to being free of having to use *the one and only true event 58 In addition to being free of having to use *the one and only true event
59 model*, AnyEvent also is free of bloat and policy: with POE or similar 59 model*, AnyEvent also is free of bloat and policy: with POE or similar
60 modules, you get an enourmous amount of code and strict rules you have 60 modules, you get an enormous amount of code and strict rules you have to
61 to follow. AnyEvent, on the other hand, is lean and up to the point, by 61 follow. AnyEvent, on the other hand, is lean and up to the point, by
62 only offering the functionality that is necessary, in as thin as a 62 only offering the functionality that is necessary, in as thin as a
63 wrapper as technically possible. 63 wrapper as technically possible.
64 64
65 Of course, if you want lots of policy (this can arguably be somewhat 65 Of course, if you want lots of policy (this can arguably be somewhat
66 useful) and you want to force your users to use the one and only event 66 useful) and you want to force your users to use the one and only event
… …
75 The interface itself is vaguely similar, but not identical to the Event 75 The interface itself is vaguely similar, but not identical to the Event
76 module. 76 module.
77 77
78 During the first call of any watcher-creation method, the module tries 78 During the first call of any watcher-creation method, the module tries
79 to detect the currently loaded event loop by probing whether one of the 79 to detect the currently loaded event loop by probing whether one of the
80 following modules is already loaded: Coro::EV, Coro::Event, EV, Event, 80 following modules is already loaded: EV, Event, Glib,
81 Glib, AnyEvent::Impl::Perl, Tk, Event::Lib, Qt, POE. The first one found 81 AnyEvent::Impl::Perl, Tk, Event::Lib, Qt, POE. The first one found is
82 is used. If none are found, the module tries to load these modules 82 used. If none are found, the module tries to load these modules
83 (excluding Tk, Event::Lib, Qt and POE as the pure perl adaptor should 83 (excluding Tk, Event::Lib, Qt and POE as the pure perl adaptor should
84 always succeed) in the order given. The first one that can be 84 always succeed) in the order given. The first one that can be
85 successfully loaded will be used. If, after this, still none could be 85 successfully loaded will be used. If, after this, still none could be
86 found, AnyEvent will fall back to a pure-perl event loop, which is not 86 found, AnyEvent will fall back to a pure-perl event loop, which is not
87 very efficient, but should work everywhere. 87 very efficient, but should work everywhere.
… …
104 explicitly. 104 explicitly.
105 105
106WATCHERS 106WATCHERS
107 AnyEvent has the central concept of a *watcher*, which is an object that 107 AnyEvent has the central concept of a *watcher*, which is an object that
108 stores relevant data for each kind of event you are waiting for, such as 108 stores relevant data for each kind of event you are waiting for, such as
109 the callback to call, the filehandle to watch, etc. 109 the callback to call, the file handle to watch, etc.
110 110
111 These watchers are normal Perl objects with normal Perl lifetime. After 111 These watchers are normal Perl objects with normal Perl lifetime. After
112 creating a watcher it will immediately "watch" for events and invoke the 112 creating a watcher it will immediately "watch" for events and invoke the
113 callback when the event occurs (of course, only when the event model is 113 callback when the event occurs (of course, only when the event model is
114 in control). 114 in control).
… …
229 229
230 Although the callback might get passed parameters, their value and 230 Although the callback might get passed parameters, their value and
231 presence is undefined and you cannot rely on them. Portable AnyEvent 231 presence is undefined and you cannot rely on them. Portable AnyEvent
232 callbacks cannot use arguments passed to signal watcher callbacks. 232 callbacks cannot use arguments passed to signal watcher callbacks.
233 233
234 Multiple signal occurances can be clumped together into one callback 234 Multiple signal occurrences can be clumped together into one callback
235 invocation, and callback invocation will be synchronous. synchronous 235 invocation, and callback invocation will be synchronous. Synchronous
236 means that it might take a while until the signal gets handled by the 236 means that it might take a while until the signal gets handled by the
237 process, but it is guarenteed not to interrupt any other callbacks. 237 process, but it is guaranteed not to interrupt any other callbacks.
238 238
239 The main advantage of using these watchers is that you can share a 239 The main advantage of using these watchers is that you can share a
240 signal between multiple watchers. 240 signal between multiple watchers.
241 241
242 This watcher might use %SIG, so programs overwriting those signals 242 This watcher might use %SIG, so programs overwriting those signals
… …
271 271
272 Example: fork a process and wait for it 272 Example: fork a process and wait for it
273 273
274 my $done = AnyEvent->condvar; 274 my $done = AnyEvent->condvar;
275 275
276 AnyEvent::detect; # force event module to be initialised
277
278 my $pid = fork or exit 5; 276 my $pid = fork or exit 5;
279 277
280 my $w = AnyEvent->child ( 278 my $w = AnyEvent->child (
281 pid => $pid, 279 pid => $pid,
282 cb => sub { 280 cb => sub {
283 my ($pid, $status) = @_; 281 my ($pid, $status) = @_;
284 warn "pid $pid exited with status $status"; 282 warn "pid $pid exited with status $status";
285 $done->broadcast; 283 $done->send;
286 }, 284 },
287 ); 285 );
288 286
289 # do something else, then wait for process exit 287 # do something else, then wait for process exit
290 $done->wait; 288 $done->recv;
291 289
292 CONDITION VARIABLES 290 CONDITION VARIABLES
291 If you are familiar with some event loops you will know that all of them
292 require you to run some blocking "loop", "run" or similar function that
293 will actively watch for new events and call your callbacks.
294
295 AnyEvent is different, it expects somebody else to run the event loop
296 and will only block when necessary (usually when told by the user).
297
298 The instrument to do that is called a "condition variable", so called
299 because they represent a condition that must become true.
300
293 Condition variables can be created by calling the "AnyEvent->condvar" 301 Condition variables can be created by calling the "AnyEvent->condvar"
294 method without any arguments. 302 method, usually without arguments. The only argument pair allowed is
303 "cb", which specifies a callback to be called when the condition
304 variable becomes true.
295 305
296 A condition variable waits for a condition - precisely that the 306 After creation, the condition variable is "false" until it becomes
297 "->broadcast" method has been called. 307 "true" by calling the "send" method (or calling the condition variable
308 as if it were a callback, read about the caveats in the description for
309 the "->send" method).
298 310
299 They are very useful to signal that a condition has been fulfilled, for 311 Condition variables are similar to callbacks, except that you can
312 optionally wait for them. They can also be called merge points - points
313 in time where multiple outstanding events have been processed. And yet
314 another way to call them is transactions - each condition variable can
315 be used to represent a transaction, which finishes at some point and
316 delivers a result.
317
318 Condition variables are very useful to signal that something has
300 example, if you write a module that does asynchronous http requests, 319 finished, for example, if you write a module that does asynchronous http
301 then a condition variable would be the ideal candidate to signal the 320 requests, then a condition variable would be the ideal candidate to
302 availability of results. 321 signal the availability of results. The user can either act when the
322 callback is called or can synchronously "->recv" for the results.
303 323
304 You can also use condition variables to block your main program until an 324 You can also use them to simulate traditional event loops - for example,
305 event occurs - for example, you could "->wait" in your main program 325 you can block your main program until an event occurs - for example, you
306 until the user clicks the Quit button in your app, which would 326 could "->recv" in your main program until the user clicks the Quit
307 "->broadcast" the "quit" event. 327 button of your app, which would "->send" the "quit" event.
308 328
309 Note that condition variables recurse into the event loop - if you have 329 Note that condition variables recurse into the event loop - if you have
310 two pirces of code that call "->wait" in a round-robbin fashion, you 330 two pieces of code that call "->recv" in a round-robin fashion, you
311 lose. Therefore, condition variables are good to export to your caller, 331 lose. Therefore, condition variables are good to export to your caller,
312 but you should avoid making a blocking wait yourself, at least in 332 but you should avoid making a blocking wait yourself, at least in
313 callbacks, as this asks for trouble. 333 callbacks, as this asks for trouble.
314 334
315 This object has two methods: 335 Condition variables are represented by hash refs in perl, and the keys
336 used by AnyEvent itself are all named "_ae_XXX" to make subclassing easy
337 (it is often useful to build your own transaction class on top of
338 AnyEvent). To subclass, use "AnyEvent::CondVar" as base class and call
339 it's "new" method in your own "new" method.
316 340
317 $cv->wait 341 There are two "sides" to a condition variable - the "producer side"
342 which eventually calls "-> send", and the "consumer side", which waits
343 for the send to occur.
344
345 Example: wait for a timer.
346
347 # wait till the result is ready
348 my $result_ready = AnyEvent->condvar;
349
350 # do something such as adding a timer
351 # or socket watcher the calls $result_ready->send
352 # when the "result" is ready.
353 # in this case, we simply use a timer:
354 my $w = AnyEvent->timer (
355 after => 1,
356 cb => sub { $result_ready->send },
357 );
358
359 # this "blocks" (while handling events) till the callback
360 # calls send
361 $result_ready->recv;
362
363 Example: wait for a timer, but take advantage of the fact that condition
364 variables are also code references.
365
366 my $done = AnyEvent->condvar;
367 my $delay = AnyEvent->timer (after => 5, cb => $done);
368 $done->recv;
369
370 METHODS FOR PRODUCERS
371 These methods should only be used by the producing side, i.e. the
372 code/module that eventually sends the signal. Note that it is also the
373 producer side which creates the condvar in most cases, but it isn't
374 uncommon for the consumer to create it as well.
375
376 $cv->send (...)
377 Flag the condition as ready - a running "->recv" and all further
378 calls to "recv" will (eventually) return after this method has been
379 called. If nobody is waiting the send will be remembered.
380
381 If a callback has been set on the condition variable, it is called
382 immediately from within send.
383
384 Any arguments passed to the "send" call will be returned by all
385 future "->recv" calls.
386
387 Condition variables are overloaded so one can call them directly (as
388 a code reference). Calling them directly is the same as calling
389 "send". Note, however, that many C-based event loops do not handle
390 overloading, so as tempting as it may be, passing a condition
391 variable instead of a callback does not work. Both the pure perl and
392 EV loops support overloading, however, as well as all functions that
393 use perl to invoke a callback (as in AnyEvent::Socket and
394 AnyEvent::DNS for example).
395
396 $cv->croak ($error)
397 Similar to send, but causes all call's to "->recv" to invoke
398 "Carp::croak" with the given error message/object/scalar.
399
400 This can be used to signal any errors to the condition variable
401 user/consumer.
402
403 $cv->begin ([group callback])
404 $cv->end
405 These two methods are EXPERIMENTAL and MIGHT CHANGE.
406
407 These two methods can be used to combine many transactions/events
408 into one. For example, a function that pings many hosts in parallel
409 might want to use a condition variable for the whole process.
410
411 Every call to "->begin" will increment a counter, and every call to
412 "->end" will decrement it. If the counter reaches 0 in "->end", the
413 (last) callback passed to "begin" will be executed. That callback is
414 *supposed* to call "->send", but that is not required. If no
415 callback was set, "send" will be called without any arguments.
416
417 Let's clarify this with the ping example:
418
419 my $cv = AnyEvent->condvar;
420
421 my %result;
422 $cv->begin (sub { $cv->send (\%result) });
423
424 for my $host (@list_of_hosts) {
425 $cv->begin;
426 ping_host_then_call_callback $host, sub {
427 $result{$host} = ...;
428 $cv->end;
429 };
430 }
431
432 $cv->end;
433
434 This code fragment supposedly pings a number of hosts and calls
435 "send" after results for all then have have been gathered - in any
436 order. To achieve this, the code issues a call to "begin" when it
437 starts each ping request and calls "end" when it has received some
438 result for it. Since "begin" and "end" only maintain a counter, the
439 order in which results arrive is not relevant.
440
441 There is an additional bracketing call to "begin" and "end" outside
442 the loop, which serves two important purposes: first, it sets the
443 callback to be called once the counter reaches 0, and second, it
444 ensures that "send" is called even when "no" hosts are being pinged
445 (the loop doesn't execute once).
446
447 This is the general pattern when you "fan out" into multiple
448 subrequests: use an outer "begin"/"end" pair to set the callback and
449 ensure "end" is called at least once, and then, for each subrequest
450 you start, call "begin" and for each subrequest you finish, call
451 "end".
452
453 METHODS FOR CONSUMERS
454 These methods should only be used by the consuming side, i.e. the code
455 awaits the condition.
456
457 $cv->recv
318 Wait (blocking if necessary) until the "->broadcast" method has been 458 Wait (blocking if necessary) until the "->send" or "->croak" methods
319 called on c<$cv>, while servicing other watchers normally. 459 have been called on c<$cv>, while servicing other watchers normally.
320 460
321 You can only wait once on a condition - additional calls will return 461 You can only wait once on a condition - additional calls are valid
322 immediately. 462 but will return immediately.
463
464 If an error condition has been set by calling "->croak", then this
465 function will call "croak".
466
467 In list context, all parameters passed to "send" will be returned,
468 in scalar context only the first one will be returned.
323 469
324 Not all event models support a blocking wait - some die in that case 470 Not all event models support a blocking wait - some die in that case
325 (programs might want to do that to stay interactive), so *if you are 471 (programs might want to do that to stay interactive), so *if you are
326 using this from a module, never require a blocking wait*, but let 472 using this from a module, never require a blocking wait*, but let
327 the caller decide whether the call will block or not (for example, 473 the caller decide whether the call will block or not (for example,
328 by coupling condition variables with some kind of request results 474 by coupling condition variables with some kind of request results
329 and supporting callbacks so the caller knows that getting the result 475 and supporting callbacks so the caller knows that getting the result
330 will not block, while still suppporting blocking waits if the caller 476 will not block, while still supporting blocking waits if the caller
331 so desires). 477 so desires).
332 478
333 Another reason *never* to "->wait" in a module is that you cannot 479 Another reason *never* to "->recv" in a module is that you cannot
334 sensibly have two "->wait"'s in parallel, as that would require 480 sensibly have two "->recv"'s in parallel, as that would require
335 multiple interpreters or coroutines/threads, none of which 481 multiple interpreters or coroutines/threads, none of which
336 "AnyEvent" can supply (the coroutine-aware backends 482 "AnyEvent" can supply.
337 AnyEvent::Impl::CoroEV and AnyEvent::Impl::CoroEvent explicitly
338 support concurrent "->wait"'s from different coroutines, however).
339 483
340 $cv->broadcast 484 The Coro module, however, *can* and *does* supply coroutines and, in
341 Flag the condition as ready - a running "->wait" and all further 485 fact, Coro::AnyEvent replaces AnyEvent's condvars by coroutine-safe
342 calls to "wait" will (eventually) return after this method has been 486 versions and also integrates coroutines into AnyEvent, making
343 called. If nobody is waiting the broadcast will be remembered.. 487 blocking "->recv" calls perfectly safe as long as they are done from
488 another coroutine (one that doesn't run the event loop).
344 489
345 Example: 490 You can ensure that "-recv" never blocks by setting a callback and
491 only calling "->recv" from within that callback (or at a later
492 time). This will work even when the event loop does not support
493 blocking waits otherwise.
346 494
347 # wait till the result is ready 495 $bool = $cv->ready
348 my $result_ready = AnyEvent->condvar; 496 Returns true when the condition is "true", i.e. whether "send" or
497 "croak" have been called.
349 498
350 # do something such as adding a timer 499 $cb = $cv->cb ([new callback])
351 # or socket watcher the calls $result_ready->broadcast 500 This is a mutator function that returns the callback set and
352 # when the "result" is ready. 501 optionally replaces it before doing so.
353 # in this case, we simply use a timer:
354 my $w = AnyEvent->timer (
355 after => 1,
356 cb => sub { $result_ready->broadcast },
357 );
358 502
359 # this "blocks" (while handling events) till the watcher 503 The callback will be called when the condition becomes "true", i.e.
360 # calls broadcast 504 when "send" or "croak" are called. Calling "recv" inside the
361 $result_ready->wait; 505 callback or at any later time is guaranteed not to block.
362 506
363GLOBAL VARIABLES AND FUNCTIONS 507GLOBAL VARIABLES AND FUNCTIONS
364 $AnyEvent::MODEL 508 $AnyEvent::MODEL
365 Contains "undef" until the first watcher is being created. Then it 509 Contains "undef" until the first watcher is being created. Then it
366 contains the event model that is being used, which is the name of 510 contains the event model that is being used, which is the name of
… …
368 the "AnyEvent::Impl:xxx" modules, but can be any other class in the 512 the "AnyEvent::Impl:xxx" modules, but can be any other class in the
369 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). 513 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*).
370 514
371 The known classes so far are: 515 The known classes so far are:
372 516
373 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
374 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
375 AnyEvent::Impl::EV based on EV (an interface to libev, best choice). 517 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
376 AnyEvent::Impl::Event based on Event, second best choice. 518 AnyEvent::Impl::Event based on Event, second best choice.
519 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
377 AnyEvent::Impl::Glib based on Glib, third-best choice. 520 AnyEvent::Impl::Glib based on Glib, third-best choice.
378 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
379 AnyEvent::Impl::Tk based on Tk, very bad choice. 521 AnyEvent::Impl::Tk based on Tk, very bad choice.
380 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs). 522 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
381 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 523 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
382 AnyEvent::Impl::POE based on POE, not generic enough for full support. 524 AnyEvent::Impl::POE based on POE, not generic enough for full support.
383 525
… …
395 Returns $AnyEvent::MODEL, forcing autodetection of the event model 537 Returns $AnyEvent::MODEL, forcing autodetection of the event model
396 if necessary. You should only call this function right before you 538 if necessary. You should only call this function right before you
397 would have created an AnyEvent watcher anyway, that is, as late as 539 would have created an AnyEvent watcher anyway, that is, as late as
398 possible at runtime. 540 possible at runtime.
399 541
542 $guard = AnyEvent::post_detect { BLOCK }
543 Arranges for the code block to be executed as soon as the event
544 model is autodetected (or immediately if this has already happened).
545
546 If called in scalar or list context, then it creates and returns an
547 object that automatically removes the callback again when it is
548 destroyed. See Coro::BDB for a case where this is useful.
549
550 @AnyEvent::post_detect
551 If there are any code references in this array (you can "push" to it
552 before or after loading AnyEvent), then they will called directly
553 after the event loop has been chosen.
554
555 You should check $AnyEvent::MODEL before adding to this array,
556 though: if it contains a true value then the event loop has already
557 been detected, and the array will be ignored.
558
559 Best use "AnyEvent::post_detect { BLOCK }" instead.
560
400WHAT TO DO IN A MODULE 561WHAT TO DO IN A MODULE
401 As a module author, you should "use AnyEvent" and call AnyEvent methods 562 As a module author, you should "use AnyEvent" and call AnyEvent methods
402 freely, but you should not load a specific event module or rely on it. 563 freely, but you should not load a specific event module or rely on it.
403 564
404 Be careful when you create watchers in the module body - AnyEvent will 565 Be careful when you create watchers in the module body - AnyEvent will
405 decide which event module to use as soon as the first method is called, 566 decide which event module to use as soon as the first method is called,
406 so by calling AnyEvent in your module body you force the user of your 567 so by calling AnyEvent in your module body you force the user of your
407 module to load the event module first. 568 module to load the event module first.
408 569
409 Never call "->wait" on a condition variable unless you *know* that the 570 Never call "->recv" on a condition variable unless you *know* that the
410 "->broadcast" method has been called on it already. This is because it 571 "->send" method has been called on it already. This is because it will
411 will stall the whole program, and the whole point of using events is to 572 stall the whole program, and the whole point of using events is to stay
412 stay interactive. 573 interactive.
413 574
414 It is fine, however, to call "->wait" when the user of your module 575 It is fine, however, to call "->recv" when the user of your module
415 requests it (i.e. if you create a http request object ad have a method 576 requests it (i.e. if you create a http request object ad have a method
416 called "results" that returns the results, it should call "->wait" 577 called "results" that returns the results, it should call "->recv"
417 freely, as the user of your module knows what she is doing. always). 578 freely, as the user of your module knows what she is doing. always).
418 579
419WHAT TO DO IN THE MAIN PROGRAM 580WHAT TO DO IN THE MAIN PROGRAM
420 There will always be a single main program - the only place that should 581 There will always be a single main program - the only place that should
421 dictate which event model to use. 582 dictate which event model to use.
… …
423 If it doesn't care, it can just "use AnyEvent" and use it itself, or not 584 If it doesn't care, it can just "use AnyEvent" and use it itself, or not
424 do anything special (it does not need to be event-based) and let 585 do anything special (it does not need to be event-based) and let
425 AnyEvent decide which implementation to chose if some module relies on 586 AnyEvent decide which implementation to chose if some module relies on
426 it. 587 it.
427 588
428 If the main program relies on a specific event model. For example, in 589 If the main program relies on a specific event model - for example, in
429 Gtk2 programs you have to rely on the Glib module. You should load the 590 Gtk2 programs you have to rely on the Glib module - you should load the
430 event module before loading AnyEvent or any module that uses it: 591 event module before loading AnyEvent or any module that uses it:
431 generally speaking, you should load it as early as possible. The reason 592 generally speaking, you should load it as early as possible. The reason
432 is that modules might create watchers when they are loaded, and AnyEvent 593 is that modules might create watchers when they are loaded, and AnyEvent
433 will decide on the event model to use as soon as it creates watchers, 594 will decide on the event model to use as soon as it creates watchers,
434 and it might chose the wrong one unless you load the correct one 595 and it might chose the wrong one unless you load the correct one
435 yourself. 596 yourself.
436 597
437 You can chose to use a rather inefficient pure-perl implementation by 598 You can chose to use a pure-perl implementation by loading the
438 loading the "AnyEvent::Impl::Perl" module, which gives you similar 599 "AnyEvent::Impl::Perl" module, which gives you similar behaviour
439 behaviour everywhere, but letting AnyEvent chose is generally better. 600 everywhere, but letting AnyEvent chose the model is generally better.
601
602 MAINLOOP EMULATION
603 Sometimes (often for short test scripts, or even standalone programs who
604 only want to use AnyEvent), you do not want to run a specific event
605 loop.
606
607 In that case, you can use a condition variable like this:
608
609 AnyEvent->condvar->recv;
610
611 This has the effect of entering the event loop and looping forever.
612
613 Note that usually your program has some exit condition, in which case it
614 is better to use the "traditional" approach of storing a condition
615 variable somewhere, waiting for it, and sending it when the program
616 should exit cleanly.
440 617
441OTHER MODULES 618OTHER MODULES
442 The following is a non-exhaustive list of additional modules that use 619 The following is a non-exhaustive list of additional modules that use
443 AnyEvent and can therefore be mixed easily with other AnyEvent modules 620 AnyEvent and can therefore be mixed easily with other AnyEvent modules
444 in the same program. Some of the modules come with AnyEvent, some are 621 in the same program. Some of the modules come with AnyEvent, some are
… …
452 AnyEvent::Handle 629 AnyEvent::Handle
453 Provide read and write buffers and manages watchers for reads and 630 Provide read and write buffers and manages watchers for reads and
454 writes. 631 writes.
455 632
456 AnyEvent::Socket 633 AnyEvent::Socket
457 Provides a means to do non-blocking connects, accepts etc. 634 Provides various utility functions for (internet protocol) sockets,
635 addresses and name resolution. Also functions to create non-blocking
636 tcp connections or tcp servers, with IPv6 and SRV record support and
637 more.
638
639 AnyEvent::DNS
640 Provides rich asynchronous DNS resolver capabilities.
458 641
459 AnyEvent::HTTPD 642 AnyEvent::HTTPD
460 Provides a simple web application server framework. 643 Provides a simple web application server framework.
461
462 AnyEvent::DNS
463 Provides asynchronous DNS resolver capabilities, beyond what
464 AnyEvent::Util offers.
465 644
466 AnyEvent::FastPing 645 AnyEvent::FastPing
467 The fastest ping in the west. 646 The fastest ping in the west.
468 647
469 Net::IRC3 648 Net::IRC3
… …
478 657
479 Event::ExecFlow 658 Event::ExecFlow
480 High level API for event-based execution flow control. 659 High level API for event-based execution flow control.
481 660
482 Coro 661 Coro
483 Has special support for AnyEvent. 662 Has special support for AnyEvent via Coro::AnyEvent.
663
664 AnyEvent::AIO, IO::AIO
665 Truly asynchronous I/O, should be in the toolbox of every event
666 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
667 together.
668
669 AnyEvent::BDB, BDB
670 Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently
671 fuses IO::AIO and AnyEvent together.
484 672
485 IO::Lambda 673 IO::Lambda
486 The lambda approach to I/O - don't ask, look there. Can use 674 The lambda approach to I/O - don't ask, look there. Can use
487 AnyEvent.
488
489 IO::AIO
490 Truly asynchronous I/O, should be in the toolbox of every event
491 programmer. Can be trivially made to use AnyEvent.
492
493 BDB Truly asynchronous Berkeley DB access. Can be trivially made to use
494 AnyEvent. 675 AnyEvent.
495 676
496SUPPLYING YOUR OWN EVENT MODEL INTERFACE 677SUPPLYING YOUR OWN EVENT MODEL INTERFACE
497 This is an advanced topic that you do not normally need to use AnyEvent 678 This is an advanced topic that you do not normally need to use AnyEvent
498 in a module. This section is only of use to event loop authors who want 679 in a module. This section is only of use to event loop authors who want
… …
551 When set to 2 or higher, cause AnyEvent to report to STDERR which 732 When set to 2 or higher, cause AnyEvent to report to STDERR which
552 event model it chooses. 733 event model it chooses.
553 734
554 "PERL_ANYEVENT_MODEL" 735 "PERL_ANYEVENT_MODEL"
555 This can be used to specify the event model to be used by AnyEvent, 736 This can be used to specify the event model to be used by AnyEvent,
556 before autodetection and -probing kicks in. It must be a string 737 before auto detection and -probing kicks in. It must be a string
557 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 738 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
558 gets prepended and the resulting module name is loaded and if the 739 gets prepended and the resulting module name is loaded and if the
559 load was successful, used as event model. If it fails to load 740 load was successful, used as event model. If it fails to load
560 AnyEvent will proceed with autodetection and -probing. 741 AnyEvent will proceed with auto detection and -probing.
561 742
562 This functionality might change in future versions. 743 This functionality might change in future versions.
563 744
564 For example, to force the pure perl model (AnyEvent::Impl::Perl) you 745 For example, to force the pure perl model (AnyEvent::Impl::Perl) you
565 could start your program like this: 746 could start your program like this:
566 747
567 PERL_ANYEVENT_MODEL=Perl perl ... 748 PERL_ANYEVENT_MODEL=Perl perl ...
749
750 "PERL_ANYEVENT_PROTOCOLS"
751 Used by both AnyEvent::DNS and AnyEvent::Socket to determine
752 preferences for IPv4 or IPv6. The default is unspecified (and might
753 change, or be the result of auto probing).
754
755 Must be set to a comma-separated list of protocols or address
756 families, current supported: "ipv4" and "ipv6". Only protocols
757 mentioned will be used, and preference will be given to protocols
758 mentioned earlier in the list.
759
760 This variable can effectively be used for denial-of-service attacks
761 against local programs (e.g. when setuid), although the impact is
762 likely small, as the program has to handle connection errors
763 already-
764
765 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
766 IPv6, but support both and try to use both.
767 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
768 resolve or contact IPv6 addresses.
769 "PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4" support either IPv4 or IPv6, but
770 prefer IPv6 over IPv4.
771
772 "PERL_ANYEVENT_EDNS0"
773 Used by AnyEvent::DNS to decide whether to use the EDNS0 extension
774 for DNS. This extension is generally useful to reduce DNS traffic,
775 but some (broken) firewalls drop such DNS packets, which is why it
776 is off by default.
777
778 Setting this variable to 1 will cause AnyEvent::DNS to announce
779 EDNS0 in its DNS requests.
568 780
569EXAMPLE PROGRAM 781EXAMPLE PROGRAM
570 The following program uses an I/O watcher to read data from STDIN, a 782 The following program uses an I/O watcher to read data from STDIN, a
571 timer to display a message once per second, and a condition variable to 783 timer to display a message once per second, and a condition variable to
572 quit the program when the user enters quit: 784 quit the program when the user enters quit:
… …
580 poll => 'r', 792 poll => 'r',
581 cb => sub { 793 cb => sub {
582 warn "io event <$_[0]>\n"; # will always output <r> 794 warn "io event <$_[0]>\n"; # will always output <r>
583 chomp (my $input = <STDIN>); # read a line 795 chomp (my $input = <STDIN>); # read a line
584 warn "read: $input\n"; # output what has been read 796 warn "read: $input\n"; # output what has been read
585 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 797 $cv->send if $input =~ /^q/i; # quit program if /^q/i
586 }, 798 },
587 ); 799 );
588 800
589 my $time_watcher; # can only be used once 801 my $time_watcher; # can only be used once
590 802
… …
595 }); 807 });
596 } 808 }
597 809
598 new_timer; # create first timer 810 new_timer; # create first timer
599 811
600 $cv->wait; # wait until user enters /^q/i 812 $cv->recv; # wait until user enters /^q/i
601 813
602REAL-WORLD EXAMPLE 814REAL-WORLD EXAMPLE
603 Consider the Net::FCP module. It features (among others) the following 815 Consider the Net::FCP module. It features (among others) the following
604 API calls, which are to freenet what HTTP GET requests are to http: 816 API calls, which are to freenet what HTTP GET requests are to http:
605 817
… …
654 syswrite $txn->{fh}, $txn->{request} 866 syswrite $txn->{fh}, $txn->{request}
655 or die "connection or write error"; 867 or die "connection or write error";
656 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r }); 868 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r });
657 869
658 Again, "fh_ready_r" waits till all data has arrived, and then stores the 870 Again, "fh_ready_r" waits till all data has arrived, and then stores the
659 result and signals any possible waiters that the request ahs finished: 871 result and signals any possible waiters that the request has finished:
660 872
661 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 873 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
662 874
663 if (end-of-file or data complete) { 875 if (end-of-file or data complete) {
664 $txn->{result} = $txn->{buf}; 876 $txn->{result} = $txn->{buf};
665 $txn->{finished}->broadcast; 877 $txn->{finished}->send;
666 $txb->{cb}->($txn) of $txn->{cb}; # also call callback 878 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
667 } 879 }
668 880
669 The "result" method, finally, just waits for the finished signal (if the 881 The "result" method, finally, just waits for the finished signal (if the
670 request was already finished, it doesn't wait, of course, and returns 882 request was already finished, it doesn't wait, of course, and returns
671 the data: 883 the data:
672 884
673 $txn->{finished}->wait; 885 $txn->{finished}->recv;
674 return $txn->{result}; 886 return $txn->{result};
675 887
676 The actual code goes further and collects all errors ("die"s, 888 The actual code goes further and collects all errors ("die"s,
677 exceptions) that occured during request processing. The "result" method 889 exceptions) that occurred during request processing. The "result" method
678 detects whether an exception as thrown (it is stored inside the $txn 890 detects whether an exception as thrown (it is stored inside the $txn
679 object) and just throws the exception, which means connection errors and 891 object) and just throws the exception, which means connection errors and
680 other problems get reported tot he code that tries to use the result, 892 other problems get reported tot he code that tries to use the result,
681 not in a random callback. 893 not in a random callback.
682 894
… …
713 925
714 my $quit = AnyEvent->condvar; 926 my $quit = AnyEvent->condvar;
715 927
716 $fcp->txn_client_get ($url)->cb (sub { 928 $fcp->txn_client_get ($url)->cb (sub {
717 ... 929 ...
718 $quit->broadcast; 930 $quit->send;
719 }); 931 });
720 932
721 $quit->wait; 933 $quit->recv;
722 934
723BENCHMARKS 935BENCHMARKS
724 To give you an idea of the performance and overheads that AnyEvent adds 936 To give you an idea of the performance and overheads that AnyEvent adds
725 over the event loops themselves and to give you an impression of the 937 over the event loops themselves and to give you an impression of the
726 speed of various event loops I prepared some benchmarks. 938 speed of various event loops I prepared some benchmarks.
727 939
728 BENCHMARKING ANYEVENT OVERHEAD 940 BENCHMARKING ANYEVENT OVERHEAD
729 Here is a benchmark of various supported event models used natively and 941 Here is a benchmark of various supported event models used natively and
730 through anyevent. The benchmark creates a lot of timers (with a zero 942 through AnyEvent. The benchmark creates a lot of timers (with a zero
731 timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 943 timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
732 which it is), lets them fire exactly once and destroys them again. 944 which it is), lets them fire exactly once and destroys them again.
733 945
734 Source code for this benchmark is found as eg/bench in the AnyEvent 946 Source code for this benchmark is found as eg/bench in the AnyEvent
735 distribution. 947 distribution.
… …
751 between all watchers, to avoid adding memory overhead. That means 963 between all watchers, to avoid adding memory overhead. That means
752 closure creation and memory usage is not included in the figures. 964 closure creation and memory usage is not included in the figures.
753 965
754 *invoke* is the time, in microseconds, used to invoke a simple callback. 966 *invoke* is the time, in microseconds, used to invoke a simple callback.
755 The callback simply counts down a Perl variable and after it was invoked 967 The callback simply counts down a Perl variable and after it was invoked
756 "watcher" times, it would "->broadcast" a condvar once to signal the end 968 "watcher" times, it would "->send" a condvar once to signal the end of
757 of this phase. 969 this phase.
758 970
759 *destroy* is the time, in microseconds, that it takes to destroy a 971 *destroy* is the time, in microseconds, that it takes to destroy a
760 single watcher. 972 single watcher.
761 973
762 Results 974 Results
… …
823 the figures above). 1035 the figures above).
824 1036
825 "POE", regardless of underlying event loop (whether using its pure perl 1037 "POE", regardless of underlying event loop (whether using its pure perl
826 select-based backend or the Event module, the POE-EV backend couldn't be 1038 select-based backend or the Event module, the POE-EV backend couldn't be
827 tested because it wasn't working) shows abysmal performance and memory 1039 tested because it wasn't working) shows abysmal performance and memory
828 usage: Watchers use almost 30 times as much memory as EV watchers, and 1040 usage with AnyEvent: Watchers use almost 30 times as much memory as EV
829 10 times as much memory as Event (the high memory requirements are 1041 watchers, and 10 times as much memory as Event (the high memory
830 caused by requiring a session for each watcher). Watcher invocation 1042 requirements are caused by requiring a session for each watcher).
831 speed is almost 900 times slower than with AnyEvent's pure perl 1043 Watcher invocation speed is almost 900 times slower than with AnyEvent's
1044 pure perl implementation.
1045
832 implementation. The design of the POE adaptor class in AnyEvent can not 1046 The design of the POE adaptor class in AnyEvent can not really account
833 really account for this, as session creation overhead is small compared 1047 for the performance issues, though, as session creation overhead is
834 to execution of the state machine, which is coded pretty optimally 1048 small compared to execution of the state machine, which is coded pretty
835 within AnyEvent::Impl::POE. POE simply seems to be abysmally slow. 1049 optimally within AnyEvent::Impl::POE (and while everybody agrees that
1050 using multiple sessions is not a good approach, especially regarding
1051 memory usage, even the author of POE could not come up with a faster
1052 design).
836 1053
837 Summary 1054 Summary
838 * Using EV through AnyEvent is faster than any other event loop (even 1055 * Using EV through AnyEvent is faster than any other event loop (even
839 when used without AnyEvent), but most event loops have acceptable 1056 when used without AnyEvent), but most event loops have acceptable
840 performance with or without AnyEvent. 1057 performance with or without AnyEvent.
… …
845 1062
846 * You should avoid POE like the plague if you want performance or 1063 * You should avoid POE like the plague if you want performance or
847 reasonable memory usage. 1064 reasonable memory usage.
848 1065
849 BENCHMARKING THE LARGE SERVER CASE 1066 BENCHMARKING THE LARGE SERVER CASE
850 This benchmark atcually benchmarks the event loop itself. It works by 1067 This benchmark actually benchmarks the event loop itself. It works by
851 creating a number of "servers": each server consists of a socketpair, a 1068 creating a number of "servers": each server consists of a socket pair, a
852 timeout watcher that gets reset on activity (but never fires), and an 1069 timeout watcher that gets reset on activity (but never fires), and an
853 I/O watcher waiting for input on one side of the socket. Each time the 1070 I/O watcher waiting for input on one side of the socket. Each time the
854 socket watcher reads a byte it will write that byte to a random other 1071 socket watcher reads a byte it will write that byte to a random other
855 "server". 1072 "server".
856 1073
857 The effect is that there will be a lot of I/O watchers, only part of 1074 The effect is that there will be a lot of I/O watchers, only part of
858 which are active at any one point (so there is a constant number of 1075 which are active at any one point (so there is a constant number of
859 active fds for each loop iterstaion, but which fds these are is random). 1076 active fds for each loop iteration, but which fds these are is random).
860 The timeout is reset each time something is read because that reflects 1077 The timeout is reset each time something is read because that reflects
861 how most timeouts work (and puts extra pressure on the event loops). 1078 how most timeouts work (and puts extra pressure on the event loops).
862 1079
863 In this benchmark, we use 10000 socketpairs (20000 sockets), of which 1080 In this benchmark, we use 10000 socket pairs (20000 sockets), of which
864 100 (1%) are active. This mirrors the activity of large servers with 1081 100 (1%) are active. This mirrors the activity of large servers with
865 many connections, most of which are idle at any one point in time. 1082 many connections, most of which are idle at any one point in time.
866 1083
867 Source code for this benchmark is found as eg/bench2 in the AnyEvent 1084 Source code for this benchmark is found as eg/bench2 in the AnyEvent
868 distribution. 1085 distribution.
869 1086
870 Explanation of the columns 1087 Explanation of the columns
871 *sockets* is the number of sockets, and twice the number of "servers" 1088 *sockets* is the number of sockets, and twice the number of "servers"
872 (as each server has a read and write socket end). 1089 (as each server has a read and write socket end).
873 1090
874 *create* is the time it takes to create a socketpair (which is 1091 *create* is the time it takes to create a socket pair (which is
875 nontrivial) and two watchers: an I/O watcher and a timeout watcher. 1092 nontrivial) and two watchers: an I/O watcher and a timeout watcher.
876 1093
877 *request*, the most important value, is the time it takes to handle a 1094 *request*, the most important value, is the time it takes to handle a
878 single "request", that is, reading the token from the pipe and 1095 single "request", that is, reading the token from the pipe and
879 forwarding it to another server. This includes deleting the old timeout 1096 forwarding it to another server. This includes deleting the old timeout
… …
909 POE is still completely out of the picture, taking over 1000 times as 1126 POE is still completely out of the picture, taking over 1000 times as
910 long as EV, and over 100 times as long as the Perl implementation, even 1127 long as EV, and over 100 times as long as the Perl implementation, even
911 though it uses a C-based event loop in this case. 1128 though it uses a C-based event loop in this case.
912 1129
913 Summary 1130 Summary
914 * The pure perl implementation performs extremely well, considering 1131 * The pure perl implementation performs extremely well.
915 that it uses select.
916 1132
917 * Avoid Glib or POE in large projects where performance matters. 1133 * Avoid Glib or POE in large projects where performance matters.
918 1134
919 BENCHMARKING SMALL SERVERS 1135 BENCHMARKING SMALL SERVERS
920 While event loops should scale (and select-based ones do not...) even to 1136 While event loops should scale (and select-based ones do not...) even to
… …
944 and speed most when you have lots of watchers, not when you only have a 1160 and speed most when you have lots of watchers, not when you only have a
945 few of them). 1161 few of them).
946 1162
947 EV is again fastest. 1163 EV is again fastest.
948 1164
949 Perl again comes second. It is noticably faster than the C-based event 1165 Perl again comes second. It is noticeably faster than the C-based event
950 loops Event and Glib, although the difference is too small to really 1166 loops Event and Glib, although the difference is too small to really
951 matter. 1167 matter.
952 1168
953 POE also performs much better in this case, but is is still far behind 1169 POE also performs much better in this case, but is is still far behind
954 the others. 1170 the others.
… …
957 * C-based event loops perform very well with small number of watchers, 1173 * C-based event loops perform very well with small number of watchers,
958 as the management overhead dominates. 1174 as the management overhead dominates.
959 1175
960FORK 1176FORK
961 Most event libraries are not fork-safe. The ones who are usually are 1177 Most event libraries are not fork-safe. The ones who are usually are
962 because they are so inefficient. Only EV is fully fork-aware. 1178 because they rely on inefficient but fork-safe "select" or "poll" calls.
1179 Only EV is fully fork-aware.
963 1180
964 If you have to fork, you must either do so *before* creating your first 1181 If you have to fork, you must either do so *before* creating your first
965 watcher OR you must not use AnyEvent at all in the child. 1182 watcher OR you must not use AnyEvent at all in the child.
966 1183
967SECURITY CONSIDERATIONS 1184SECURITY CONSIDERATIONS
… …
977 1194
978 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1195 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
979 1196
980 use AnyEvent; 1197 use AnyEvent;
981 1198
1199 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1200 be used to probe what backend is used and gain other information (which
1201 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1202
982SEE ALSO 1203SEE ALSO
983 Event modules: Coro::EV, EV, EV::Glib, Glib::EV, Coro::Event, Event, 1204 Utility functions: AnyEvent::Util.
984 Glib::Event, Glib, Coro, Tk, Event::Lib, Qt, POE.
985 1205
986 Implementations: AnyEvent::Impl::CoroEV, AnyEvent::Impl::EV, 1206 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
987 AnyEvent::Impl::CoroEvent, AnyEvent::Impl::Event, AnyEvent::Impl::Glib, 1207 Event::Lib, Qt, POE.
988 AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, AnyEvent::Impl::EventLib, 1208
1209 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1210 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
989 AnyEvent::Impl::Qt, AnyEvent::Impl::POE. 1211 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE.
990 1212
1213 Non-blocking file handles, sockets, TCP clients and servers:
1214 AnyEvent::Handle, AnyEvent::Socket.
1215
1216 Asynchronous DNS: AnyEvent::DNS.
1217
1218 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1219
991 Nontrivial usage examples: Net::FCP, Net::XMPP2. 1220 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS.
992 1221
993AUTHOR 1222AUTHOR
994 Marc Lehmann <schmorp@schmorp.de> 1223 Marc Lehmann <schmorp@schmorp.de>
995 http://home.schmorp.de/ 1224 http://home.schmorp.de/
996 1225

Diff Legend

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