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.22 by root, Sat May 24 17:58:33 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).
298 309
299 They are very useful to signal that a condition has been fulfilled, for 310 Condition variables are similar to callbacks, except that you can
311 optionally wait for them. They can also be called merge points - points
312 in time where multiple outstanding events have been processed. And yet
313 another way to call them is transactions - each condition variable can
314 be used to represent a transaction, which finishes at some point and
315 delivers a result.
316
317 Condition variables are very useful to signal that something has
300 example, if you write a module that does asynchronous http requests, 318 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 319 requests, then a condition variable would be the ideal candidate to
302 availability of results. 320 signal the availability of results. The user can either act when the
321 callback is called or can synchronously "->recv" for the results.
303 322
304 You can also use condition variables to block your main program until an 323 You can also use them to simulate traditional event loops - for example,
305 event occurs - for example, you could "->wait" in your main program 324 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 325 could "->recv" in your main program until the user clicks the Quit
307 "->broadcast" the "quit" event. 326 button of your app, which would "->send" the "quit" event.
308 327
309 Note that condition variables recurse into the event loop - if you have 328 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 329 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, 330 lose. Therefore, condition variables are good to export to your caller,
312 but you should avoid making a blocking wait yourself, at least in 331 but you should avoid making a blocking wait yourself, at least in
313 callbacks, as this asks for trouble. 332 callbacks, as this asks for trouble.
314 333
315 This object has two methods: 334 Condition variables are represented by hash refs in perl, and the keys
335 used by AnyEvent itself are all named "_ae_XXX" to make subclassing easy
336 (it is often useful to build your own transaction class on top of
337 AnyEvent). To subclass, use "AnyEvent::CondVar" as base class and call
338 it's "new" method in your own "new" method.
316 339
317 $cv->wait 340 There are two "sides" to a condition variable - the "producer side"
341 which eventually calls "-> send", and the "consumer side", which waits
342 for the send to occur.
343
344 Example: wait for a timer.
345
346 # wait till the result is ready
347 my $result_ready = AnyEvent->condvar;
348
349 # do something such as adding a timer
350 # or socket watcher the calls $result_ready->send
351 # when the "result" is ready.
352 # in this case, we simply use a timer:
353 my $w = AnyEvent->timer (
354 after => 1,
355 cb => sub { $result_ready->send },
356 );
357
358 # this "blocks" (while handling events) till the callback
359 # calls send
360 $result_ready->recv;
361
362 Example: wait for a timer, but take advantage of the fact that condition
363 variables are also code references.
364
365 my $done = AnyEvent->condvar;
366 my $delay = AnyEvent->timer (after => 5, cb => $done);
367 $done->recv;
368
369 METHODS FOR PRODUCERS
370 These methods should only be used by the producing side, i.e. the
371 code/module that eventually sends the signal. Note that it is also the
372 producer side which creates the condvar in most cases, but it isn't
373 uncommon for the consumer to create it as well.
374
375 $cv->send (...)
376 Flag the condition as ready - a running "->recv" and all further
377 calls to "recv" will (eventually) return after this method has been
378 called. If nobody is waiting the send will be remembered.
379
380 If a callback has been set on the condition variable, it is called
381 immediately from within send.
382
383 Any arguments passed to the "send" call will be returned by all
384 future "->recv" calls.
385
386 Condition variables are overloaded so one can call them directly (as
387 a code reference). Calling them directly is the same as calling
388 "send".
389
390 $cv->croak ($error)
391 Similar to send, but causes all call's to "->recv" to invoke
392 "Carp::croak" with the given error message/object/scalar.
393
394 This can be used to signal any errors to the condition variable
395 user/consumer.
396
397 $cv->begin ([group callback])
398 $cv->end
399 These two methods are EXPERIMENTAL and MIGHT CHANGE.
400
401 These two methods can be used to combine many transactions/events
402 into one. For example, a function that pings many hosts in parallel
403 might want to use a condition variable for the whole process.
404
405 Every call to "->begin" will increment a counter, and every call to
406 "->end" will decrement it. If the counter reaches 0 in "->end", the
407 (last) callback passed to "begin" will be executed. That callback is
408 *supposed* to call "->send", but that is not required. If no
409 callback was set, "send" will be called without any arguments.
410
411 Let's clarify this with the ping example:
412
413 my $cv = AnyEvent->condvar;
414
415 my %result;
416 $cv->begin (sub { $cv->send (\%result) });
417
418 for my $host (@list_of_hosts) {
419 $cv->begin;
420 ping_host_then_call_callback $host, sub {
421 $result{$host} = ...;
422 $cv->end;
423 };
424 }
425
426 $cv->end;
427
428 This code fragment supposedly pings a number of hosts and calls
429 "send" after results for all then have have been gathered - in any
430 order. To achieve this, the code issues a call to "begin" when it
431 starts each ping request and calls "end" when it has received some
432 result for it. Since "begin" and "end" only maintain a counter, the
433 order in which results arrive is not relevant.
434
435 There is an additional bracketing call to "begin" and "end" outside
436 the loop, which serves two important purposes: first, it sets the
437 callback to be called once the counter reaches 0, and second, it
438 ensures that "send" is called even when "no" hosts are being pinged
439 (the loop doesn't execute once).
440
441 This is the general pattern when you "fan out" into multiple
442 subrequests: use an outer "begin"/"end" pair to set the callback and
443 ensure "end" is called at least once, and then, for each subrequest
444 you start, call "begin" and for each subrequest you finish, call
445 "end".
446
447 METHODS FOR CONSUMERS
448 These methods should only be used by the consuming side, i.e. the code
449 awaits the condition.
450
451 $cv->recv
318 Wait (blocking if necessary) until the "->broadcast" method has been 452 Wait (blocking if necessary) until the "->send" or "->croak" methods
319 called on c<$cv>, while servicing other watchers normally. 453 have been called on c<$cv>, while servicing other watchers normally.
320 454
321 You can only wait once on a condition - additional calls will return 455 You can only wait once on a condition - additional calls are valid
322 immediately. 456 but will return immediately.
457
458 If an error condition has been set by calling "->croak", then this
459 function will call "croak".
460
461 In list context, all parameters passed to "send" will be returned,
462 in scalar context only the first one will be returned.
323 463
324 Not all event models support a blocking wait - some die in that case 464 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 465 (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 466 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, 467 the caller decide whether the call will block or not (for example,
328 by coupling condition variables with some kind of request results 468 by coupling condition variables with some kind of request results
329 and supporting callbacks so the caller knows that getting the result 469 and supporting callbacks so the caller knows that getting the result
330 will not block, while still suppporting blocking waits if the caller 470 will not block, while still supporting blocking waits if the caller
331 so desires). 471 so desires).
332 472
333 Another reason *never* to "->wait" in a module is that you cannot 473 Another reason *never* to "->recv" in a module is that you cannot
334 sensibly have two "->wait"'s in parallel, as that would require 474 sensibly have two "->recv"'s in parallel, as that would require
335 multiple interpreters or coroutines/threads, none of which 475 multiple interpreters or coroutines/threads, none of which
336 "AnyEvent" can supply (the coroutine-aware backends 476 "AnyEvent" can supply.
337 AnyEvent::Impl::CoroEV and AnyEvent::Impl::CoroEvent explicitly
338 support concurrent "->wait"'s from different coroutines, however).
339 477
340 $cv->broadcast 478 The Coro module, however, *can* and *does* supply coroutines and, in
341 Flag the condition as ready - a running "->wait" and all further 479 fact, Coro::AnyEvent replaces AnyEvent's condvars by coroutine-safe
342 calls to "wait" will (eventually) return after this method has been 480 versions and also integrates coroutines into AnyEvent, making
343 called. If nobody is waiting the broadcast will be remembered.. 481 blocking "->recv" calls perfectly safe as long as they are done from
482 another coroutine (one that doesn't run the event loop).
344 483
345 Example: 484 You can ensure that "-recv" never blocks by setting a callback and
485 only calling "->recv" from within that callback (or at a later
486 time). This will work even when the event loop does not support
487 blocking waits otherwise.
346 488
347 # wait till the result is ready 489 $bool = $cv->ready
348 my $result_ready = AnyEvent->condvar; 490 Returns true when the condition is "true", i.e. whether "send" or
491 "croak" have been called.
349 492
350 # do something such as adding a timer 493 $cb = $cv->cb ([new callback])
351 # or socket watcher the calls $result_ready->broadcast 494 This is a mutator function that returns the callback set and
352 # when the "result" is ready. 495 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 496
359 # this "blocks" (while handling events) till the watcher 497 The callback will be called when the condition becomes "true", i.e.
360 # calls broadcast 498 when "send" or "croak" are called. Calling "recv" inside the
361 $result_ready->wait; 499 callback or at any later time is guaranteed not to block.
362 500
363GLOBAL VARIABLES AND FUNCTIONS 501GLOBAL VARIABLES AND FUNCTIONS
364 $AnyEvent::MODEL 502 $AnyEvent::MODEL
365 Contains "undef" until the first watcher is being created. Then it 503 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 504 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 506 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*). 507 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*).
370 508
371 The known classes so far are: 509 The known classes so far are:
372 510
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). 511 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
376 AnyEvent::Impl::Event based on Event, second best choice. 512 AnyEvent::Impl::Event based on Event, second best choice.
513 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
377 AnyEvent::Impl::Glib based on Glib, third-best choice. 514 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. 515 AnyEvent::Impl::Tk based on Tk, very bad choice.
380 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs). 516 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
381 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 517 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
382 AnyEvent::Impl::POE based on POE, not generic enough for full support. 518 AnyEvent::Impl::POE based on POE, not generic enough for full support.
383 519
… …
395 Returns $AnyEvent::MODEL, forcing autodetection of the event model 531 Returns $AnyEvent::MODEL, forcing autodetection of the event model
396 if necessary. You should only call this function right before you 532 if necessary. You should only call this function right before you
397 would have created an AnyEvent watcher anyway, that is, as late as 533 would have created an AnyEvent watcher anyway, that is, as late as
398 possible at runtime. 534 possible at runtime.
399 535
536 $guard = AnyEvent::post_detect { BLOCK }
537 Arranges for the code block to be executed as soon as the event
538 model is autodetected (or immediately if this has already happened).
539
540 If called in scalar or list context, then it creates and returns an
541 object that automatically removes the callback again when it is
542 destroyed. See Coro::BDB for a case where this is useful.
543
544 @AnyEvent::post_detect
545 If there are any code references in this array (you can "push" to it
546 before or after loading AnyEvent), then they will called directly
547 after the event loop has been chosen.
548
549 You should check $AnyEvent::MODEL before adding to this array,
550 though: if it contains a true value then the event loop has already
551 been detected, and the array will be ignored.
552
553 Best use "AnyEvent::post_detect { BLOCK }" instead.
554
400WHAT TO DO IN A MODULE 555WHAT TO DO IN A MODULE
401 As a module author, you should "use AnyEvent" and call AnyEvent methods 556 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. 557 freely, but you should not load a specific event module or rely on it.
403 558
404 Be careful when you create watchers in the module body - AnyEvent will 559 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, 560 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 561 so by calling AnyEvent in your module body you force the user of your
407 module to load the event module first. 562 module to load the event module first.
408 563
409 Never call "->wait" on a condition variable unless you *know* that the 564 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 565 "->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 566 stall the whole program, and the whole point of using events is to stay
412 stay interactive. 567 interactive.
413 568
414 It is fine, however, to call "->wait" when the user of your module 569 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 570 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" 571 called "results" that returns the results, it should call "->recv"
417 freely, as the user of your module knows what she is doing. always). 572 freely, as the user of your module knows what she is doing. always).
418 573
419WHAT TO DO IN THE MAIN PROGRAM 574WHAT TO DO IN THE MAIN PROGRAM
420 There will always be a single main program - the only place that should 575 There will always be a single main program - the only place that should
421 dictate which event model to use. 576 dictate which event model to use.
… …
452 AnyEvent::Handle 607 AnyEvent::Handle
453 Provide read and write buffers and manages watchers for reads and 608 Provide read and write buffers and manages watchers for reads and
454 writes. 609 writes.
455 610
456 AnyEvent::Socket 611 AnyEvent::Socket
457 Provides a means to do non-blocking connects, accepts etc. 612 Provides various utility functions for (internet protocol) sockets,
613 addresses and name resolution. Also functions to create non-blocking
614 tcp connections or tcp servers, with IPv6 and SRV record support and
615 more.
458 616
459 AnyEvent::HTTPD 617 AnyEvent::HTTPD
460 Provides a simple web application server framework. 618 Provides a simple web application server framework.
461 619
462 AnyEvent::DNS 620 AnyEvent::DNS
463 Provides asynchronous DNS resolver capabilities, beyond what 621 Provides rich asynchronous DNS resolver capabilities.
464 AnyEvent::Util offers.
465 622
466 AnyEvent::FastPing 623 AnyEvent::FastPing
467 The fastest ping in the west. 624 The fastest ping in the west.
468 625
469 Net::IRC3 626 Net::IRC3
… …
478 635
479 Event::ExecFlow 636 Event::ExecFlow
480 High level API for event-based execution flow control. 637 High level API for event-based execution flow control.
481 638
482 Coro 639 Coro
483 Has special support for AnyEvent. 640 Has special support for AnyEvent via Coro::AnyEvent.
641
642 AnyEvent::AIO, IO::AIO
643 Truly asynchronous I/O, should be in the toolbox of every event
644 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
645 together.
646
647 AnyEvent::BDB, BDB
648 Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently
649 fuses IO::AIO and AnyEvent together.
484 650
485 IO::Lambda 651 IO::Lambda
486 The lambda approach to I/O - don't ask, look there. Can use 652 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. 653 AnyEvent.
495 654
496SUPPLYING YOUR OWN EVENT MODEL INTERFACE 655SUPPLYING YOUR OWN EVENT MODEL INTERFACE
497 This is an advanced topic that you do not normally need to use AnyEvent 656 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 657 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 710 When set to 2 or higher, cause AnyEvent to report to STDERR which
552 event model it chooses. 711 event model it chooses.
553 712
554 "PERL_ANYEVENT_MODEL" 713 "PERL_ANYEVENT_MODEL"
555 This can be used to specify the event model to be used by AnyEvent, 714 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 715 before auto detection and -probing kicks in. It must be a string
557 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 716 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
558 gets prepended and the resulting module name is loaded and if the 717 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 718 load was successful, used as event model. If it fails to load
560 AnyEvent will proceed with autodetection and -probing. 719 AnyEvent will proceed with auto detection and -probing.
561 720
562 This functionality might change in future versions. 721 This functionality might change in future versions.
563 722
564 For example, to force the pure perl model (AnyEvent::Impl::Perl) you 723 For example, to force the pure perl model (AnyEvent::Impl::Perl) you
565 could start your program like this: 724 could start your program like this:
566 725
567 PERL_ANYEVENT_MODEL=Perl perl ... 726 PERL_ANYEVENT_MODEL=Perl perl ...
727
728 "PERL_ANYEVENT_PROTOCOLS"
729 Used by both AnyEvent::DNS and AnyEvent::Socket to determine
730 preferences for IPv4 or IPv6. The default is unspecified (and might
731 change, or be the result of auto probing).
732
733 Must be set to a comma-separated list of protocols or address
734 families, current supported: "ipv4" and "ipv6". Only protocols
735 mentioned will be used, and preference will be given to protocols
736 mentioned earlier in the list.
737
738 This variable can effectively be used for denial-of-service attacks
739 against local programs (e.g. when setuid), although the impact is
740 likely small, as the program has to handle connection errors
741 already-
742
743 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
744 IPv6, but support both and try to use both.
745 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
746 resolve or contact IPv6 addresses.
747 "PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4" support either IPv4 or IPv6, but
748 prefer IPv6 over IPv4.
749
750 "PERL_ANYEVENT_EDNS0"
751 Used by AnyEvent::DNS to decide whether to use the EDNS0 extension
752 for DNS. This extension is generally useful to reduce DNS traffic,
753 but some (broken) firewalls drop such DNS packets, which is why it
754 is off by default.
755
756 Setting this variable to 1 will cause AnyEvent::DNS to announce
757 EDNS0 in its DNS requests.
568 758
569EXAMPLE PROGRAM 759EXAMPLE PROGRAM
570 The following program uses an I/O watcher to read data from STDIN, a 760 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 761 timer to display a message once per second, and a condition variable to
572 quit the program when the user enters quit: 762 quit the program when the user enters quit:
… …
580 poll => 'r', 770 poll => 'r',
581 cb => sub { 771 cb => sub {
582 warn "io event <$_[0]>\n"; # will always output <r> 772 warn "io event <$_[0]>\n"; # will always output <r>
583 chomp (my $input = <STDIN>); # read a line 773 chomp (my $input = <STDIN>); # read a line
584 warn "read: $input\n"; # output what has been read 774 warn "read: $input\n"; # output what has been read
585 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 775 $cv->send if $input =~ /^q/i; # quit program if /^q/i
586 }, 776 },
587 ); 777 );
588 778
589 my $time_watcher; # can only be used once 779 my $time_watcher; # can only be used once
590 780
… …
595 }); 785 });
596 } 786 }
597 787
598 new_timer; # create first timer 788 new_timer; # create first timer
599 789
600 $cv->wait; # wait until user enters /^q/i 790 $cv->recv; # wait until user enters /^q/i
601 791
602REAL-WORLD EXAMPLE 792REAL-WORLD EXAMPLE
603 Consider the Net::FCP module. It features (among others) the following 793 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: 794 API calls, which are to freenet what HTTP GET requests are to http:
605 795
… …
654 syswrite $txn->{fh}, $txn->{request} 844 syswrite $txn->{fh}, $txn->{request}
655 or die "connection or write error"; 845 or die "connection or write error";
656 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r }); 846 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r });
657 847
658 Again, "fh_ready_r" waits till all data has arrived, and then stores the 848 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: 849 result and signals any possible waiters that the request has finished:
660 850
661 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 851 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
662 852
663 if (end-of-file or data complete) { 853 if (end-of-file or data complete) {
664 $txn->{result} = $txn->{buf}; 854 $txn->{result} = $txn->{buf};
665 $txn->{finished}->broadcast; 855 $txn->{finished}->send;
666 $txb->{cb}->($txn) of $txn->{cb}; # also call callback 856 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
667 } 857 }
668 858
669 The "result" method, finally, just waits for the finished signal (if the 859 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 860 request was already finished, it doesn't wait, of course, and returns
671 the data: 861 the data:
672 862
673 $txn->{finished}->wait; 863 $txn->{finished}->recv;
674 return $txn->{result}; 864 return $txn->{result};
675 865
676 The actual code goes further and collects all errors ("die"s, 866 The actual code goes further and collects all errors ("die"s,
677 exceptions) that occured during request processing. The "result" method 867 exceptions) that occurred during request processing. The "result" method
678 detects whether an exception as thrown (it is stored inside the $txn 868 detects whether an exception as thrown (it is stored inside the $txn
679 object) and just throws the exception, which means connection errors and 869 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, 870 other problems get reported tot he code that tries to use the result,
681 not in a random callback. 871 not in a random callback.
682 872
… …
713 903
714 my $quit = AnyEvent->condvar; 904 my $quit = AnyEvent->condvar;
715 905
716 $fcp->txn_client_get ($url)->cb (sub { 906 $fcp->txn_client_get ($url)->cb (sub {
717 ... 907 ...
718 $quit->broadcast; 908 $quit->send;
719 }); 909 });
720 910
721 $quit->wait; 911 $quit->recv;
722 912
723BENCHMARKS 913BENCHMARKS
724 To give you an idea of the performance and overheads that AnyEvent adds 914 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 915 over the event loops themselves and to give you an impression of the
726 speed of various event loops I prepared some benchmarks. 916 speed of various event loops I prepared some benchmarks.
727 917
728 BENCHMARKING ANYEVENT OVERHEAD 918 BENCHMARKING ANYEVENT OVERHEAD
729 Here is a benchmark of various supported event models used natively and 919 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 920 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, 921 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. 922 which it is), lets them fire exactly once and destroys them again.
733 923
734 Source code for this benchmark is found as eg/bench in the AnyEvent 924 Source code for this benchmark is found as eg/bench in the AnyEvent
735 distribution. 925 distribution.
… …
751 between all watchers, to avoid adding memory overhead. That means 941 between all watchers, to avoid adding memory overhead. That means
752 closure creation and memory usage is not included in the figures. 942 closure creation and memory usage is not included in the figures.
753 943
754 *invoke* is the time, in microseconds, used to invoke a simple callback. 944 *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 945 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 946 "watcher" times, it would "->send" a condvar once to signal the end of
757 of this phase. 947 this phase.
758 948
759 *destroy* is the time, in microseconds, that it takes to destroy a 949 *destroy* is the time, in microseconds, that it takes to destroy a
760 single watcher. 950 single watcher.
761 951
762 Results 952 Results
… …
823 the figures above). 1013 the figures above).
824 1014
825 "POE", regardless of underlying event loop (whether using its pure perl 1015 "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 1016 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 1017 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 1018 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 1019 watchers, and 10 times as much memory as Event (the high memory
830 caused by requiring a session for each watcher). Watcher invocation 1020 requirements are caused by requiring a session for each watcher).
831 speed is almost 900 times slower than with AnyEvent's pure perl 1021 Watcher invocation speed is almost 900 times slower than with AnyEvent's
1022 pure perl implementation.
1023
832 implementation. The design of the POE adaptor class in AnyEvent can not 1024 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 1025 for the performance issues, though, as session creation overhead is
834 to execution of the state machine, which is coded pretty optimally 1026 small compared to execution of the state machine, which is coded pretty
835 within AnyEvent::Impl::POE. POE simply seems to be abysmally slow. 1027 optimally within AnyEvent::Impl::POE (and while everybody agrees that
1028 using multiple sessions is not a good approach, especially regarding
1029 memory usage, even the author of POE could not come up with a faster
1030 design).
836 1031
837 Summary 1032 Summary
838 * Using EV through AnyEvent is faster than any other event loop (even 1033 * Using EV through AnyEvent is faster than any other event loop (even
839 when used without AnyEvent), but most event loops have acceptable 1034 when used without AnyEvent), but most event loops have acceptable
840 performance with or without AnyEvent. 1035 performance with or without AnyEvent.
… …
845 1040
846 * You should avoid POE like the plague if you want performance or 1041 * You should avoid POE like the plague if you want performance or
847 reasonable memory usage. 1042 reasonable memory usage.
848 1043
849 BENCHMARKING THE LARGE SERVER CASE 1044 BENCHMARKING THE LARGE SERVER CASE
850 This benchmark atcually benchmarks the event loop itself. It works by 1045 This benchmark actually benchmarks the event loop itself. It works by
851 creating a number of "servers": each server consists of a socketpair, a 1046 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 1047 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 1048 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 1049 socket watcher reads a byte it will write that byte to a random other
855 "server". 1050 "server".
856 1051
857 The effect is that there will be a lot of I/O watchers, only part of 1052 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 1053 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). 1054 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 1055 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). 1056 how most timeouts work (and puts extra pressure on the event loops).
862 1057
863 In this benchmark, we use 10000 socketpairs (20000 sockets), of which 1058 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 1059 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. 1060 many connections, most of which are idle at any one point in time.
866 1061
867 Source code for this benchmark is found as eg/bench2 in the AnyEvent 1062 Source code for this benchmark is found as eg/bench2 in the AnyEvent
868 distribution. 1063 distribution.
869 1064
870 Explanation of the columns 1065 Explanation of the columns
871 *sockets* is the number of sockets, and twice the number of "servers" 1066 *sockets* is the number of sockets, and twice the number of "servers"
872 (as each server has a read and write socket end). 1067 (as each server has a read and write socket end).
873 1068
874 *create* is the time it takes to create a socketpair (which is 1069 *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. 1070 nontrivial) and two watchers: an I/O watcher and a timeout watcher.
876 1071
877 *request*, the most important value, is the time it takes to handle a 1072 *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 1073 single "request", that is, reading the token from the pipe and
879 forwarding it to another server. This includes deleting the old timeout 1074 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 1104 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 1105 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. 1106 though it uses a C-based event loop in this case.
912 1107
913 Summary 1108 Summary
914 * The pure perl implementation performs extremely well, considering 1109 * The pure perl implementation performs extremely well.
915 that it uses select.
916 1110
917 * Avoid Glib or POE in large projects where performance matters. 1111 * Avoid Glib or POE in large projects where performance matters.
918 1112
919 BENCHMARKING SMALL SERVERS 1113 BENCHMARKING SMALL SERVERS
920 While event loops should scale (and select-based ones do not...) even to 1114 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 1138 and speed most when you have lots of watchers, not when you only have a
945 few of them). 1139 few of them).
946 1140
947 EV is again fastest. 1141 EV is again fastest.
948 1142
949 Perl again comes second. It is noticably faster than the C-based event 1143 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 1144 loops Event and Glib, although the difference is too small to really
951 matter. 1145 matter.
952 1146
953 POE also performs much better in this case, but is is still far behind 1147 POE also performs much better in this case, but is is still far behind
954 the others. 1148 the others.
… …
957 * C-based event loops perform very well with small number of watchers, 1151 * C-based event loops perform very well with small number of watchers,
958 as the management overhead dominates. 1152 as the management overhead dominates.
959 1153
960FORK 1154FORK
961 Most event libraries are not fork-safe. The ones who are usually are 1155 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. 1156 because they rely on inefficient but fork-safe "select" or "poll" calls.
1157 Only EV is fully fork-aware.
963 1158
964 If you have to fork, you must either do so *before* creating your first 1159 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. 1160 watcher OR you must not use AnyEvent at all in the child.
966 1161
967SECURITY CONSIDERATIONS 1162SECURITY CONSIDERATIONS
… …
977 1172
978 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1173 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
979 1174
980 use AnyEvent; 1175 use AnyEvent;
981 1176
1177 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1178 be used to probe what backend is used and gain other information (which
1179 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1180
982SEE ALSO 1181SEE ALSO
983 Event modules: Coro::EV, EV, EV::Glib, Glib::EV, Coro::Event, Event, 1182 Utility functions: AnyEvent::Util.
984 Glib::Event, Glib, Coro, Tk, Event::Lib, Qt, POE.
985 1183
986 Implementations: AnyEvent::Impl::CoroEV, AnyEvent::Impl::EV, 1184 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
987 AnyEvent::Impl::CoroEvent, AnyEvent::Impl::Event, AnyEvent::Impl::Glib, 1185 Event::Lib, Qt, POE.
988 AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, AnyEvent::Impl::EventLib, 1186
1187 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1188 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
989 AnyEvent::Impl::Qt, AnyEvent::Impl::POE. 1189 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE.
990 1190
1191 Non-blocking file handles, sockets, TCP clients and servers:
1192 AnyEvent::Handle, AnyEvent::Socket.
1193
1194 Asynchronous DNS: AnyEvent::DNS.
1195
1196 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1197
991 Nontrivial usage examples: Net::FCP, Net::XMPP2. 1198 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS.
992 1199
993AUTHOR 1200AUTHOR
994 Marc Lehmann <schmorp@schmorp.de> 1201 Marc Lehmann <schmorp@schmorp.de>
995 http://home.schmorp.de/ 1202 http://home.schmorp.de/
996 1203

Diff Legend

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