1 | NAME |
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 | |
7 | SYNOPSIS |
7 | SYNOPSIS |
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 | |
22 | WHY YOU SHOULD USE THIS MODULE (OR NOT) |
22 | WHY 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 | |
… | |
… | |
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. |
… | |
… | |
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 conditon variable is "false" until it becomes "true" |
297 | "->broadcast" method has been called. |
307 | by calling the "send" method. |
298 | |
308 | |
299 | They are very useful to signal that a condition has been fulfilled, for |
309 | Condition variables are similar to callbacks, except that you can |
|
|
310 | optionally wait for them. They can also be called merge points - points |
|
|
311 | in time where multiple outstandign events have been processed. And yet |
|
|
312 | another way to call them is transations - each condition variable can be |
|
|
313 | used to represent a transaction, which finishes at some point and |
|
|
314 | delivers a result. |
|
|
315 | |
|
|
316 | Condition variables are very useful to signal that something has |
300 | example, if you write a module that does asynchronous http requests, |
317 | 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 |
318 | requests, then a condition variable would be the ideal candidate to |
302 | availability of results. |
319 | signal the availability of results. The user can either act when the |
|
|
320 | callback is called or can synchronously "->recv" for the results. |
303 | |
321 | |
304 | You can also use condition variables to block your main program until an |
322 | You can also use them to simulate traditional event loops - for example, |
305 | event occurs - for example, you could "->wait" in your main program |
323 | 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 |
324 | could "->recv" in your main program until the user clicks the Quit |
307 | "->broadcast" the "quit" event. |
325 | button of your app, which would "->send" the "quit" event. |
308 | |
326 | |
309 | Note that condition variables recurse into the event loop - if you have |
327 | 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 |
328 | two pieces of code that call "->recv" in a round-robbin fashion, you |
311 | lose. Therefore, condition variables are good to export to your caller, |
329 | lose. Therefore, condition variables are good to export to your caller, |
312 | but you should avoid making a blocking wait yourself, at least in |
330 | but you should avoid making a blocking wait yourself, at least in |
313 | callbacks, as this asks for trouble. |
331 | callbacks, as this asks for trouble. |
314 | |
332 | |
315 | This object has two methods: |
333 | Condition variables are represented by hash refs in perl, and the keys |
|
|
334 | used by AnyEvent itself are all named "_ae_XXX" to make subclassing easy |
|
|
335 | (it is often useful to build your own transaction class on top of |
|
|
336 | AnyEvent). To subclass, use "AnyEvent::CondVar" as base class and call |
|
|
337 | it's "new" method in your own "new" method. |
316 | |
338 | |
317 | $cv->wait |
339 | There are two "sides" to a condition variable - the "producer side" |
|
|
340 | which eventually calls "-> send", and the "consumer side", which waits |
|
|
341 | for the send to occur. |
|
|
342 | |
|
|
343 | Example: |
|
|
344 | |
|
|
345 | # wait till the result is ready |
|
|
346 | my $result_ready = AnyEvent->condvar; |
|
|
347 | |
|
|
348 | # do something such as adding a timer |
|
|
349 | # or socket watcher the calls $result_ready->send |
|
|
350 | # when the "result" is ready. |
|
|
351 | # in this case, we simply use a timer: |
|
|
352 | my $w = AnyEvent->timer ( |
|
|
353 | after => 1, |
|
|
354 | cb => sub { $result_ready->send }, |
|
|
355 | ); |
|
|
356 | |
|
|
357 | # this "blocks" (while handling events) till the callback |
|
|
358 | # calls send |
|
|
359 | $result_ready->recv; |
|
|
360 | |
|
|
361 | METHODS FOR PRODUCERS |
|
|
362 | These methods should only be used by the producing side, i.e. the |
|
|
363 | code/module that eventually sends the signal. Note that it is also the |
|
|
364 | producer side which creates the condvar in most cases, but it isn't |
|
|
365 | uncommon for the consumer to create it as well. |
|
|
366 | |
|
|
367 | $cv->send (...) |
|
|
368 | Flag the condition as ready - a running "->recv" and all further |
|
|
369 | calls to "recv" will (eventually) return after this method has been |
|
|
370 | called. If nobody is waiting the send will be remembered. |
|
|
371 | |
|
|
372 | If a callback has been set on the condition variable, it is called |
|
|
373 | immediately from within send. |
|
|
374 | |
|
|
375 | Any arguments passed to the "send" call will be returned by all |
|
|
376 | future "->recv" calls. |
|
|
377 | |
|
|
378 | $cv->croak ($error) |
|
|
379 | Similar to send, but causes all call's to "->recv" to invoke |
|
|
380 | "Carp::croak" with the given error message/object/scalar. |
|
|
381 | |
|
|
382 | This can be used to signal any errors to the condition variable |
|
|
383 | user/consumer. |
|
|
384 | |
|
|
385 | $cv->begin ([group callback]) |
|
|
386 | $cv->end |
|
|
387 | These two methods are EXPERIMENTAL and MIGHT CHANGE. |
|
|
388 | |
|
|
389 | These two methods can be used to combine many transactions/events |
|
|
390 | into one. For example, a function that pings many hosts in parallel |
|
|
391 | might want to use a condition variable for the whole process. |
|
|
392 | |
|
|
393 | Every call to "->begin" will increment a counter, and every call to |
|
|
394 | "->end" will decrement it. If the counter reaches 0 in "->end", the |
|
|
395 | (last) callback passed to "begin" will be executed. That callback is |
|
|
396 | *supposed* to call "->send", but that is not required. If no |
|
|
397 | callback was set, "send" will be called without any arguments. |
|
|
398 | |
|
|
399 | Let's clarify this with the ping example: |
|
|
400 | |
|
|
401 | my $cv = AnyEvent->condvar; |
|
|
402 | |
|
|
403 | my %result; |
|
|
404 | $cv->begin (sub { $cv->send (\%result) }); |
|
|
405 | |
|
|
406 | for my $host (@list_of_hosts) { |
|
|
407 | $cv->begin; |
|
|
408 | ping_host_then_call_callback $host, sub { |
|
|
409 | $result{$host} = ...; |
|
|
410 | $cv->end; |
|
|
411 | }; |
|
|
412 | } |
|
|
413 | |
|
|
414 | $cv->end; |
|
|
415 | |
|
|
416 | This code fragment supposedly pings a number of hosts and calls |
|
|
417 | "send" after results for all then have have been gathered - in any |
|
|
418 | order. To achieve this, the code issues a call to "begin" when it |
|
|
419 | starts each ping request and calls "end" when it has received some |
|
|
420 | result for it. Since "begin" and "end" only maintain a counter, the |
|
|
421 | order in which results arrive is not relevant. |
|
|
422 | |
|
|
423 | There is an additional bracketing call to "begin" and "end" outside |
|
|
424 | the loop, which serves two important purposes: first, it sets the |
|
|
425 | callback to be called once the counter reaches 0, and second, it |
|
|
426 | ensures that "send" is called even when "no" hosts are being pinged |
|
|
427 | (the loop doesn't execute once). |
|
|
428 | |
|
|
429 | This is the general pattern when you "fan out" into multiple |
|
|
430 | subrequests: use an outer "begin"/"end" pair to set the callback and |
|
|
431 | ensure "end" is called at least once, and then, for each subrequest |
|
|
432 | you start, call "begin" and for eahc subrequest you finish, call |
|
|
433 | "end". |
|
|
434 | |
|
|
435 | METHODS FOR CONSUMERS |
|
|
436 | These methods should only be used by the consuming side, i.e. the code |
|
|
437 | awaits the condition. |
|
|
438 | |
|
|
439 | $cv->recv |
318 | Wait (blocking if necessary) until the "->broadcast" method has been |
440 | Wait (blocking if necessary) until the "->send" or "->croak" methods |
319 | called on c<$cv>, while servicing other watchers normally. |
441 | have been called on c<$cv>, while servicing other watchers normally. |
320 | |
442 | |
321 | You can only wait once on a condition - additional calls will return |
443 | You can only wait once on a condition - additional calls are valid |
322 | immediately. |
444 | but will return immediately. |
|
|
445 | |
|
|
446 | If an error condition has been set by calling "->croak", then this |
|
|
447 | function will call "croak". |
|
|
448 | |
|
|
449 | In list context, all parameters passed to "send" will be returned, |
|
|
450 | in scalar context only the first one will be returned. |
323 | |
451 | |
324 | Not all event models support a blocking wait - some die in that case |
452 | 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 |
453 | (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 |
454 | 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, |
455 | the caller decide whether the call will block or not (for example, |
328 | by coupling condition variables with some kind of request results |
456 | by coupling condition variables with some kind of request results |
329 | and supporting callbacks so the caller knows that getting the result |
457 | and supporting callbacks so the caller knows that getting the result |
330 | will not block, while still suppporting blocking waits if the caller |
458 | will not block, while still suppporting blocking waits if the caller |
331 | so desires). |
459 | so desires). |
332 | |
460 | |
333 | Another reason *never* to "->wait" in a module is that you cannot |
461 | Another reason *never* to "->recv" in a module is that you cannot |
334 | sensibly have two "->wait"'s in parallel, as that would require |
462 | sensibly have two "->recv"'s in parallel, as that would require |
335 | multiple interpreters or coroutines/threads, none of which |
463 | multiple interpreters or coroutines/threads, none of which |
336 | "AnyEvent" can supply (the coroutine-aware backends |
464 | "AnyEvent" can supply. |
337 | AnyEvent::Impl::CoroEV and AnyEvent::Impl::CoroEvent explicitly |
|
|
338 | support concurrent "->wait"'s from different coroutines, however). |
|
|
339 | |
465 | |
340 | $cv->broadcast |
466 | The Coro module, however, *can* and *does* supply coroutines and, in |
341 | Flag the condition as ready - a running "->wait" and all further |
467 | fact, Coro::AnyEvent replaces AnyEvent's condvars by coroutine-safe |
342 | calls to "wait" will (eventually) return after this method has been |
468 | versions and also integrates coroutines into AnyEvent, making |
343 | called. If nobody is waiting the broadcast will be remembered.. |
469 | blocking "->recv" calls perfectly safe as long as they are done from |
|
|
470 | another coroutine (one that doesn't run the event loop). |
344 | |
471 | |
345 | Example: |
472 | You can ensure that "-recv" never blocks by setting a callback and |
|
|
473 | only calling "->recv" from within that callback (or at a later |
|
|
474 | time). This will work even when the event loop does not support |
|
|
475 | blocking waits otherwise. |
346 | |
476 | |
347 | # wait till the result is ready |
477 | $bool = $cv->ready |
348 | my $result_ready = AnyEvent->condvar; |
478 | Returns true when the condition is "true", i.e. whether "send" or |
|
|
479 | "croak" have been called. |
349 | |
480 | |
350 | # do something such as adding a timer |
481 | $cb = $cv->cb ([new callback]) |
351 | # or socket watcher the calls $result_ready->broadcast |
482 | This is a mutator function that returns the callback set and |
352 | # when the "result" is ready. |
483 | 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 | |
484 | |
359 | # this "blocks" (while handling events) till the watcher |
485 | The callback will be called when the condition becomes "true", i.e. |
360 | # calls broadcast |
486 | when "send" or "croak" are called. Calling "recv" inside the |
361 | $result_ready->wait; |
487 | callback or at any later time is guaranteed not to block. |
362 | |
488 | |
363 | GLOBAL VARIABLES AND FUNCTIONS |
489 | GLOBAL VARIABLES AND FUNCTIONS |
364 | $AnyEvent::MODEL |
490 | $AnyEvent::MODEL |
365 | Contains "undef" until the first watcher is being created. Then it |
491 | 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 |
492 | 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 |
494 | 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*). |
495 | case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). |
370 | |
496 | |
371 | The known classes so far are: |
497 | The known classes so far are: |
372 | |
498 | |
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). |
499 | AnyEvent::Impl::EV based on EV (an interface to libev, best choice). |
376 | AnyEvent::Impl::Event based on Event, second best choice. |
500 | AnyEvent::Impl::Event based on Event, second best choice. |
|
|
501 | AnyEvent::Impl::Perl pure-perl implementation, fast and portable. |
377 | AnyEvent::Impl::Glib based on Glib, third-best choice. |
502 | 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. |
503 | AnyEvent::Impl::Tk based on Tk, very bad choice. |
380 | AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs). |
504 | AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs). |
381 | AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. |
505 | AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. |
382 | AnyEvent::Impl::POE based on POE, not generic enough for full support. |
506 | AnyEvent::Impl::POE based on POE, not generic enough for full support. |
383 | |
507 | |
… | |
… | |
395 | Returns $AnyEvent::MODEL, forcing autodetection of the event model |
519 | Returns $AnyEvent::MODEL, forcing autodetection of the event model |
396 | if necessary. You should only call this function right before you |
520 | if necessary. You should only call this function right before you |
397 | would have created an AnyEvent watcher anyway, that is, as late as |
521 | would have created an AnyEvent watcher anyway, that is, as late as |
398 | possible at runtime. |
522 | possible at runtime. |
399 | |
523 | |
|
|
524 | $guard = AnyEvent::post_detect { BLOCK } |
|
|
525 | Arranges for the code block to be executed as soon as the event |
|
|
526 | model is autodetected (or immediately if this has already happened). |
|
|
527 | |
|
|
528 | If called in scalar or list context, then it creates and returns an |
|
|
529 | object that automatically removes the callback again when it is |
|
|
530 | destroyed. See Coro::BDB for a case where this is useful. |
|
|
531 | |
|
|
532 | @AnyEvent::post_detect |
|
|
533 | If there are any code references in this array (you can "push" to it |
|
|
534 | before or after loading AnyEvent), then they will called directly |
|
|
535 | after the event loop has been chosen. |
|
|
536 | |
|
|
537 | You should check $AnyEvent::MODEL before adding to this array, |
|
|
538 | though: if it contains a true value then the event loop has already |
|
|
539 | been detected, and the array will be ignored. |
|
|
540 | |
|
|
541 | Best use "AnyEvent::post_detect { BLOCK }" instead. |
|
|
542 | |
400 | WHAT TO DO IN A MODULE |
543 | WHAT TO DO IN A MODULE |
401 | As a module author, you should "use AnyEvent" and call AnyEvent methods |
544 | 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. |
545 | freely, but you should not load a specific event module or rely on it. |
403 | |
546 | |
404 | Be careful when you create watchers in the module body - AnyEvent will |
547 | 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, |
548 | 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 |
549 | so by calling AnyEvent in your module body you force the user of your |
407 | module to load the event module first. |
550 | module to load the event module first. |
408 | |
551 | |
409 | Never call "->wait" on a condition variable unless you *know* that the |
552 | 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 |
553 | "->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 |
554 | stall the whole program, and the whole point of using events is to stay |
412 | stay interactive. |
555 | interactive. |
413 | |
556 | |
414 | It is fine, however, to call "->wait" when the user of your module |
557 | 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 |
558 | 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" |
559 | called "results" that returns the results, it should call "->recv" |
417 | freely, as the user of your module knows what she is doing. always). |
560 | freely, as the user of your module knows what she is doing. always). |
418 | |
561 | |
419 | WHAT TO DO IN THE MAIN PROGRAM |
562 | WHAT TO DO IN THE MAIN PROGRAM |
420 | There will always be a single main program - the only place that should |
563 | There will always be a single main program - the only place that should |
421 | dictate which event model to use. |
564 | dictate which event model to use. |
… | |
… | |
451 | |
594 | |
452 | AnyEvent::Handle |
595 | AnyEvent::Handle |
453 | Provide read and write buffers and manages watchers for reads and |
596 | Provide read and write buffers and manages watchers for reads and |
454 | writes. |
597 | writes. |
455 | |
598 | |
456 | AnyEvent::Socket |
|
|
457 | Provides a means to do non-blocking connects, accepts etc. |
|
|
458 | |
|
|
459 | AnyEvent::HTTPD |
599 | AnyEvent::HTTPD |
460 | Provides a simple web application server framework. |
600 | Provides a simple web application server framework. |
461 | |
601 | |
462 | AnyEvent::DNS |
602 | AnyEvent::DNS |
463 | Provides asynchronous DNS resolver capabilities, beyond what |
603 | Provides asynchronous DNS resolver capabilities, beyond what |
… | |
… | |
478 | |
618 | |
479 | Event::ExecFlow |
619 | Event::ExecFlow |
480 | High level API for event-based execution flow control. |
620 | High level API for event-based execution flow control. |
481 | |
621 | |
482 | Coro |
622 | Coro |
483 | Has special support for AnyEvent. |
623 | Has special support for AnyEvent via Coro::AnyEvent. |
|
|
624 | |
|
|
625 | AnyEvent::AIO, IO::AIO |
|
|
626 | Truly asynchronous I/O, should be in the toolbox of every event |
|
|
627 | programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent |
|
|
628 | together. |
|
|
629 | |
|
|
630 | AnyEvent::BDB, BDB |
|
|
631 | Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently |
|
|
632 | fuses IO::AIO and AnyEvent together. |
484 | |
633 | |
485 | IO::Lambda |
634 | IO::Lambda |
486 | The lambda approach to I/O - don't ask, look there. Can use |
635 | 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. |
636 | AnyEvent. |
495 | |
637 | |
496 | SUPPLYING YOUR OWN EVENT MODEL INTERFACE |
638 | SUPPLYING YOUR OWN EVENT MODEL INTERFACE |
497 | This is an advanced topic that you do not normally need to use AnyEvent |
639 | 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 |
640 | in a module. This section is only of use to event loop authors who want |
… | |
… | |
580 | poll => 'r', |
722 | poll => 'r', |
581 | cb => sub { |
723 | cb => sub { |
582 | warn "io event <$_[0]>\n"; # will always output <r> |
724 | warn "io event <$_[0]>\n"; # will always output <r> |
583 | chomp (my $input = <STDIN>); # read a line |
725 | chomp (my $input = <STDIN>); # read a line |
584 | warn "read: $input\n"; # output what has been read |
726 | warn "read: $input\n"; # output what has been read |
585 | $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i |
727 | $cv->send if $input =~ /^q/i; # quit program if /^q/i |
586 | }, |
728 | }, |
587 | ); |
729 | ); |
588 | |
730 | |
589 | my $time_watcher; # can only be used once |
731 | my $time_watcher; # can only be used once |
590 | |
732 | |
… | |
… | |
595 | }); |
737 | }); |
596 | } |
738 | } |
597 | |
739 | |
598 | new_timer; # create first timer |
740 | new_timer; # create first timer |
599 | |
741 | |
600 | $cv->wait; # wait until user enters /^q/i |
742 | $cv->recv; # wait until user enters /^q/i |
601 | |
743 | |
602 | REAL-WORLD EXAMPLE |
744 | REAL-WORLD EXAMPLE |
603 | Consider the Net::FCP module. It features (among others) the following |
745 | 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: |
746 | API calls, which are to freenet what HTTP GET requests are to http: |
605 | |
747 | |
… | |
… | |
660 | |
802 | |
661 | sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; |
803 | sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; |
662 | |
804 | |
663 | if (end-of-file or data complete) { |
805 | if (end-of-file or data complete) { |
664 | $txn->{result} = $txn->{buf}; |
806 | $txn->{result} = $txn->{buf}; |
665 | $txn->{finished}->broadcast; |
807 | $txn->{finished}->send; |
666 | $txb->{cb}->($txn) of $txn->{cb}; # also call callback |
808 | $txb->{cb}->($txn) of $txn->{cb}; # also call callback |
667 | } |
809 | } |
668 | |
810 | |
669 | The "result" method, finally, just waits for the finished signal (if the |
811 | 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 |
812 | request was already finished, it doesn't wait, of course, and returns |
671 | the data: |
813 | the data: |
672 | |
814 | |
673 | $txn->{finished}->wait; |
815 | $txn->{finished}->recv; |
674 | return $txn->{result}; |
816 | return $txn->{result}; |
675 | |
817 | |
676 | The actual code goes further and collects all errors ("die"s, |
818 | The actual code goes further and collects all errors ("die"s, |
677 | exceptions) that occured during request processing. The "result" method |
819 | exceptions) that occured during request processing. The "result" method |
678 | detects whether an exception as thrown (it is stored inside the $txn |
820 | detects whether an exception as thrown (it is stored inside the $txn |
… | |
… | |
713 | |
855 | |
714 | my $quit = AnyEvent->condvar; |
856 | my $quit = AnyEvent->condvar; |
715 | |
857 | |
716 | $fcp->txn_client_get ($url)->cb (sub { |
858 | $fcp->txn_client_get ($url)->cb (sub { |
717 | ... |
859 | ... |
718 | $quit->broadcast; |
860 | $quit->send; |
719 | }); |
861 | }); |
720 | |
862 | |
721 | $quit->wait; |
863 | $quit->recv; |
722 | |
864 | |
723 | BENCHMARKS |
865 | BENCHMARKS |
724 | To give you an idea of the performance and overheads that AnyEvent adds |
866 | 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 |
867 | over the event loops themselves and to give you an impression of the |
726 | speed of various event loops I prepared some benchmarks. |
868 | speed of various event loops I prepared some benchmarks. |
… | |
… | |
751 | between all watchers, to avoid adding memory overhead. That means |
893 | between all watchers, to avoid adding memory overhead. That means |
752 | closure creation and memory usage is not included in the figures. |
894 | closure creation and memory usage is not included in the figures. |
753 | |
895 | |
754 | *invoke* is the time, in microseconds, used to invoke a simple callback. |
896 | *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 |
897 | 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 |
898 | "watcher" times, it would "->send" a condvar once to signal the end of |
757 | of this phase. |
899 | this phase. |
758 | |
900 | |
759 | *destroy* is the time, in microseconds, that it takes to destroy a |
901 | *destroy* is the time, in microseconds, that it takes to destroy a |
760 | single watcher. |
902 | single watcher. |
761 | |
903 | |
762 | Results |
904 | Results |
… | |
… | |
823 | the figures above). |
965 | the figures above). |
824 | |
966 | |
825 | "POE", regardless of underlying event loop (whether using its pure perl |
967 | "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 |
968 | 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 |
969 | 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 |
970 | 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 |
971 | watchers, and 10 times as much memory as Event (the high memory |
830 | caused by requiring a session for each watcher). Watcher invocation |
972 | requirements are caused by requiring a session for each watcher). |
831 | speed is almost 900 times slower than with AnyEvent's pure perl |
973 | Watcher invocation speed is almost 900 times slower than with AnyEvent's |
|
|
974 | pure perl implementation. |
|
|
975 | |
832 | implementation. The design of the POE adaptor class in AnyEvent can not |
976 | 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 |
977 | for the performance issues, though, as session creation overhead is |
834 | to execution of the state machine, which is coded pretty optimally |
978 | small compared to execution of the state machine, which is coded pretty |
835 | within AnyEvent::Impl::POE. POE simply seems to be abysmally slow. |
979 | optimally within AnyEvent::Impl::POE (and while everybody agrees that |
|
|
980 | using multiple sessions is not a good approach, especially regarding |
|
|
981 | memory usage, even the author of POE could not come up with a faster |
|
|
982 | design). |
836 | |
983 | |
837 | Summary |
984 | Summary |
838 | * Using EV through AnyEvent is faster than any other event loop (even |
985 | * Using EV through AnyEvent is faster than any other event loop (even |
839 | when used without AnyEvent), but most event loops have acceptable |
986 | when used without AnyEvent), but most event loops have acceptable |
840 | performance with or without AnyEvent. |
987 | performance with or without AnyEvent. |
… | |
… | |
909 | POE is still completely out of the picture, taking over 1000 times as |
1056 | 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 |
1057 | 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. |
1058 | though it uses a C-based event loop in this case. |
912 | |
1059 | |
913 | Summary |
1060 | Summary |
914 | * The pure perl implementation performs extremely well, considering |
1061 | * The pure perl implementation performs extremely well. |
915 | that it uses select. |
|
|
916 | |
1062 | |
917 | * Avoid Glib or POE in large projects where performance matters. |
1063 | * Avoid Glib or POE in large projects where performance matters. |
918 | |
1064 | |
919 | BENCHMARKING SMALL SERVERS |
1065 | BENCHMARKING SMALL SERVERS |
920 | While event loops should scale (and select-based ones do not...) even to |
1066 | While event loops should scale (and select-based ones do not...) even to |
… | |
… | |
957 | * C-based event loops perform very well with small number of watchers, |
1103 | * C-based event loops perform very well with small number of watchers, |
958 | as the management overhead dominates. |
1104 | as the management overhead dominates. |
959 | |
1105 | |
960 | FORK |
1106 | FORK |
961 | Most event libraries are not fork-safe. The ones who are usually are |
1107 | 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. |
1108 | because they rely on inefficient but fork-safe "select" or "poll" calls. |
|
|
1109 | Only EV is fully fork-aware. |
963 | |
1110 | |
964 | If you have to fork, you must either do so *before* creating your first |
1111 | 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. |
1112 | watcher OR you must not use AnyEvent at all in the child. |
966 | |
1113 | |
967 | SECURITY CONSIDERATIONS |
1114 | SECURITY CONSIDERATIONS |
… | |
… | |
977 | |
1124 | |
978 | BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } |
1125 | BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } |
979 | |
1126 | |
980 | use AnyEvent; |
1127 | use AnyEvent; |
981 | |
1128 | |
|
|
1129 | Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can |
|
|
1130 | be used to probe what backend is used and gain other information (which |
|
|
1131 | is probably even less useful to an attacker than PERL_ANYEVENT_MODEL). |
|
|
1132 | |
982 | SEE ALSO |
1133 | SEE ALSO |
983 | Event modules: Coro::EV, EV, EV::Glib, Glib::EV, Coro::Event, Event, |
1134 | Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, |
984 | Glib::Event, Glib, Coro, Tk, Event::Lib, Qt, POE. |
1135 | Event::Lib, Qt, POE. |
985 | |
1136 | |
986 | Implementations: AnyEvent::Impl::CoroEV, AnyEvent::Impl::EV, |
1137 | Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, |
987 | AnyEvent::Impl::CoroEvent, AnyEvent::Impl::Event, AnyEvent::Impl::Glib, |
1138 | AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, |
988 | AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, AnyEvent::Impl::EventLib, |
|
|
989 | AnyEvent::Impl::Qt, AnyEvent::Impl::POE. |
1139 | AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE. |
|
|
1140 | |
|
|
1141 | Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, |
990 | |
1142 | |
991 | Nontrivial usage examples: Net::FCP, Net::XMPP2. |
1143 | Nontrivial usage examples: Net::FCP, Net::XMPP2. |
992 | |
1144 | |
993 | AUTHOR |
1145 | AUTHOR |
994 | Marc Lehmann <schmorp@schmorp.de> |
1146 | Marc Lehmann <schmorp@schmorp.de> |