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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.93 by root, Sat Apr 26 04:19:52 2008 UTC vs.
Revision 1.113 by root, Sat May 10 20:30:35 2008 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent - provide framework for multiple event loops 3AnyEvent - provide framework for multiple event loops
4 4
5EV, Event, Coro::EV, Coro::Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event loops 5EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event loops
6 6
7=head1 SYNOPSIS 7=head1 SYNOPSIS
8 8
9 use AnyEvent; 9 use AnyEvent;
10 10
15 my $w = AnyEvent->timer (after => $seconds, cb => sub { 15 my $w = AnyEvent->timer (after => $seconds, cb => sub {
16 ... 16 ...
17 }); 17 });
18 18
19 my $w = AnyEvent->condvar; # stores whether a condition was flagged 19 my $w = AnyEvent->condvar; # stores whether a condition was flagged
20 $w->wait; # enters "main loop" till $condvar gets ->broadcast 20 $w->wait; # enters "main loop" till $condvar gets ->send
21 $w->broadcast; # wake up current and all future wait's 21 $w->send; # wake up current and all future wait's
22 22
23=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT) 23=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
24 24
25Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 25Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
26nowadays. So what is different about AnyEvent? 26nowadays. So what is different about AnyEvent?
66 66
67Of course, if you want lots of policy (this can arguably be somewhat 67Of course, if you want lots of policy (this can arguably be somewhat
68useful) and you want to force your users to use the one and only event 68useful) and you want to force your users to use the one and only event
69model, you should I<not> use this module. 69model, you should I<not> use this module.
70 70
71
72=head1 DESCRIPTION 71=head1 DESCRIPTION
73 72
74L<AnyEvent> provides an identical interface to multiple event loops. This 73L<AnyEvent> provides an identical interface to multiple event loops. This
75allows module authors to utilise an event loop without forcing module 74allows module authors to utilise an event loop without forcing module
76users to use the same event loop (as only a single event loop can coexist 75users to use the same event loop (as only a single event loop can coexist
79The interface itself is vaguely similar, but not identical to the L<Event> 78The interface itself is vaguely similar, but not identical to the L<Event>
80module. 79module.
81 80
82During the first call of any watcher-creation method, the module tries 81During the first call of any watcher-creation method, the module tries
83to detect the currently loaded event loop by probing whether one of the 82to detect the currently loaded event loop by probing whether one of the
84following modules is already loaded: L<Coro::EV>, L<Coro::Event>, L<EV>, 83following modules is already loaded: L<EV>,
85L<Event>, L<Glib>, L<AnyEvent::Impl::Perl>, L<Tk>, L<Event::Lib>, L<Qt>, 84L<Event>, L<Glib>, L<AnyEvent::Impl::Perl>, L<Tk>, L<Event::Lib>, L<Qt>,
86L<POE>. The first one found is used. If none are found, the module tries 85L<POE>. The first one found is used. If none are found, the module tries
87to load these modules (excluding Tk, Event::Lib, Qt and POE as the pure perl 86to load these modules (excluding Tk, Event::Lib, Qt and POE as the pure perl
88adaptor should always succeed) in the order given. The first one that can 87adaptor should always succeed) in the order given. The first one that can
89be successfully loaded will be used. If, after this, still none could be 88be successfully loaded will be used. If, after this, still none could be
289 my $w = AnyEvent->child ( 288 my $w = AnyEvent->child (
290 pid => $pid, 289 pid => $pid,
291 cb => sub { 290 cb => sub {
292 my ($pid, $status) = @_; 291 my ($pid, $status) = @_;
293 warn "pid $pid exited with status $status"; 292 warn "pid $pid exited with status $status";
294 $done->broadcast; 293 $done->send;
295 }, 294 },
296 ); 295 );
297 296
298 # do something else, then wait for process exit 297 # do something else, then wait for process exit
299 $done->wait; 298 $done->wait;
300 299
301=head2 CONDITION VARIABLES 300=head2 CONDITION VARIABLES
302 301
302If you are familiar with some event loops you will know that all of them
303require you to run some blocking "loop", "run" or similar function that
304will actively watch for new events and call your callbacks.
305
306AnyEvent is different, it expects somebody else to run the event loop and
307will only block when necessary (usually when told by the user).
308
309The instrument to do that is called a "condition variable", so called
310because they represent a condition that must become true.
311
303Condition variables can be created by calling the C<< AnyEvent->condvar >> 312Condition variables can be created by calling the C<< AnyEvent->condvar
304method without any arguments. 313>> method, usually without arguments. The only argument pair allowed is
314C<cb>, which specifies a callback to be called when the condition variable
315becomes true.
305 316
306A condition variable waits for a condition - precisely that the C<< 317After creation, the conditon variable is "false" until it becomes "true"
307->broadcast >> method has been called. 318by calling the C<send> method.
308 319
309They are very useful to signal that a condition has been fulfilled, for 320Condition variables are similar to callbacks, except that you can
321optionally wait for them. They can also be called merge points - points
322in time where multiple outstandign events have been processed. And yet
323another way to call them is transations - each condition variable can be
324used to represent a transaction, which finishes at some point and delivers
325a result.
326
327Condition variables are very useful to signal that something has finished,
310example, if you write a module that does asynchronous http requests, 328for example, if you write a module that does asynchronous http requests,
311then a condition variable would be the ideal candidate to signal the 329then a condition variable would be the ideal candidate to signal the
312availability of results. 330availability of results. The user can either act when the callback is
331called or can synchronously C<< ->wait >> for the results.
313 332
314You can also use condition variables to block your main program until 333You can also use them to simulate traditional event loops - for example,
315an event occurs - for example, you could C<< ->wait >> in your main 334you can block your main program until an event occurs - for example, you
316program until the user clicks the Quit button in your app, which would C<< 335could C<< ->wait >> in your main program until the user clicks the Quit
317->broadcast >> the "quit" event. 336button of your app, which would C<< ->send >> the "quit" event.
318 337
319Note that condition variables recurse into the event loop - if you have 338Note that condition variables recurse into the event loop - if you have
320two pirces of code that call C<< ->wait >> in a round-robbin fashion, you 339two pieces of code that call C<< ->wait >> in a round-robbin fashion, you
321lose. Therefore, condition variables are good to export to your caller, but 340lose. Therefore, condition variables are good to export to your caller, but
322you should avoid making a blocking wait yourself, at least in callbacks, 341you should avoid making a blocking wait yourself, at least in callbacks,
323as this asks for trouble. 342as this asks for trouble.
324 343
325This object has two methods: 344Condition variables are represented by hash refs in perl, and the keys
345used by AnyEvent itself are all named C<_ae_XXX> to make subclassing
346easy (it is often useful to build your own transaction class on top of
347AnyEvent). To subclass, use C<AnyEvent::CondVar> as base class and call
348it's C<new> method in your own C<new> method.
349
350There are two "sides" to a condition variable - the "producer side" which
351eventually calls C<< -> send >>, and the "consumer side", which waits
352for the send to occur.
353
354Example:
355
356 # wait till the result is ready
357 my $result_ready = AnyEvent->condvar;
358
359 # do something such as adding a timer
360 # or socket watcher the calls $result_ready->send
361 # when the "result" is ready.
362 # in this case, we simply use a timer:
363 my $w = AnyEvent->timer (
364 after => 1,
365 cb => sub { $result_ready->send },
366 );
367
368 # this "blocks" (while handling events) till the callback
369 # calls send
370 $result_ready->wait;
371
372=head3 METHODS FOR PRODUCERS
373
374These methods should only be used by the producing side, i.e. the
375code/module that eventually sends the signal. Note that it is also
376the producer side which creates the condvar in most cases, but it isn't
377uncommon for the consumer to create it as well.
326 378
327=over 4 379=over 4
328 380
381=item $cv->send (...)
382
383Flag the condition as ready - a running C<< ->wait >> and all further
384calls to C<wait> will (eventually) return after this method has been
385called. If nobody is waiting the send will be remembered.
386
387If a callback has been set on the condition variable, it is called
388immediately from within send.
389
390Any arguments passed to the C<send> call will be returned by all
391future C<< ->wait >> calls.
392
393=item $cv->croak ($error)
394
395Similar to send, but causes all call's wait C<< ->wait >> to invoke
396C<Carp::croak> with the given error message/object/scalar.
397
398This can be used to signal any errors to the condition variable
399user/consumer.
400
401=item $cv->begin ([group callback])
402
403=item $cv->end
404
405These two methods can be used to combine many transactions/events into
406one. For example, a function that pings many hosts in parallel might want
407to use a condition variable for the whole process.
408
409Every call to C<< ->begin >> will increment a counter, and every call to
410C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end
411>>, the (last) callback passed to C<begin> will be executed. That callback
412is I<supposed> to call C<< ->send >>, but that is not required. If no
413callback was set, C<send> will be called without any arguments.
414
415Let's clarify this with the ping example:
416
417 my $cv = AnyEvent->condvar;
418
419 my %result;
420 $cv->begin (sub { $cv->send (\%result) });
421
422 for my $host (@list_of_hosts) {
423 $cv->begin;
424 ping_host_then_call_callback $host, sub {
425 $result{$host} = ...;
426 $cv->end;
427 };
428 }
429
430 $cv->end;
431
432This code fragment supposedly pings a number of hosts and calls
433C<send> after results for all then have have been gathered - in any
434order. To achieve this, the code issues a call to C<begin> when it starts
435each ping request and calls C<end> when it has received some result for
436it. Since C<begin> and C<end> only maintain a counter, the order in which
437results arrive is not relevant.
438
439There is an additional bracketing call to C<begin> and C<end> outside the
440loop, which serves two important purposes: first, it sets the callback
441to be called once the counter reaches C<0>, and second, it ensures that
442C<send> is called even when C<no> hosts are being pinged (the loop
443doesn't execute once).
444
445This is the general pattern when you "fan out" into multiple subrequests:
446use an outer C<begin>/C<end> pair to set the callback and ensure C<end>
447is called at least once, and then, for each subrequest you start, call
448C<begin> and for eahc subrequest you finish, call C<end>.
449
450=back
451
452=head3 METHODS FOR CONSUMERS
453
454These methods should only be used by the consuming side, i.e. the
455code awaits the condition.
456
457=over 4
458
329=item $cv->wait 459=item $cv->wait
330 460
331Wait (blocking if necessary) until the C<< ->broadcast >> method has been 461Wait (blocking if necessary) until the C<< ->send >> or C<< ->croak
332called on c<$cv>, while servicing other watchers normally. 462>> methods have been called on c<$cv>, while servicing other watchers
463normally.
333 464
334You can only wait once on a condition - additional calls will return 465You can only wait once on a condition - additional calls are valid but
335immediately. 466will return immediately.
467
468If an error condition has been set by calling C<< ->croak >>, then this
469function will call C<croak>.
470
471In list context, all parameters passed to C<send> will be returned,
472in scalar context only the first one will be returned.
336 473
337Not all event models support a blocking wait - some die in that case 474Not all event models support a blocking wait - some die in that case
338(programs might want to do that to stay interactive), so I<if you are 475(programs might want to do that to stay interactive), so I<if you are
339using this from a module, never require a blocking wait>, but let the 476using this from a module, never require a blocking wait>, but let the
340caller decide whether the call will block or not (for example, by coupling 477caller decide whether the call will block or not (for example, by coupling
343while still suppporting blocking waits if the caller so desires). 480while still suppporting blocking waits if the caller so desires).
344 481
345Another reason I<never> to C<< ->wait >> in a module is that you cannot 482Another reason I<never> to C<< ->wait >> in a module is that you cannot
346sensibly have two C<< ->wait >>'s in parallel, as that would require 483sensibly have two C<< ->wait >>'s in parallel, as that would require
347multiple interpreters or coroutines/threads, none of which C<AnyEvent> 484multiple interpreters or coroutines/threads, none of which C<AnyEvent>
348can supply (the coroutine-aware backends L<AnyEvent::Impl::CoroEV> and 485can supply.
349L<AnyEvent::Impl::CoroEvent> explicitly support concurrent C<< ->wait >>'s
350from different coroutines, however).
351 486
352=item $cv->broadcast 487The L<Coro> module, however, I<can> and I<does> supply coroutines and, in
488fact, L<Coro::AnyEvent> replaces AnyEvent's condvars by coroutine-safe
489versions and also integrates coroutines into AnyEvent, making blocking
490C<< ->wait >> calls perfectly safe as long as they are done from another
491coroutine (one that doesn't run the event loop).
353 492
354Flag the condition as ready - a running C<< ->wait >> and all further 493You can ensure that C<< -wait >> never blocks by setting a callback and
355calls to C<wait> will (eventually) return after this method has been 494only calling C<< ->wait >> from within that callback (or at a later
356called. If nobody is waiting the broadcast will be remembered.. 495time). This will work even when the event loop does not support blocking
496waits otherwise.
497
498=item $bool = $cv->ready
499
500Returns true when the condition is "true", i.e. whether C<send> or
501C<croak> have been called.
502
503=item $cb = $cv->cb ([new callback])
504
505This is a mutator function that returns the callback set and optionally
506replaces it before doing so.
507
508The callback will be called when the condition becomes "true", i.e. when
509C<send> or C<croak> are called. Calling C<wait> inside the callback
510or at any later time is guaranteed not to block.
357 511
358=back 512=back
359
360Example:
361
362 # wait till the result is ready
363 my $result_ready = AnyEvent->condvar;
364
365 # do something such as adding a timer
366 # or socket watcher the calls $result_ready->broadcast
367 # when the "result" is ready.
368 # in this case, we simply use a timer:
369 my $w = AnyEvent->timer (
370 after => 1,
371 cb => sub { $result_ready->broadcast },
372 );
373
374 # this "blocks" (while handling events) till the watcher
375 # calls broadcast
376 $result_ready->wait;
377 513
378=head1 GLOBAL VARIABLES AND FUNCTIONS 514=head1 GLOBAL VARIABLES AND FUNCTIONS
379 515
380=over 4 516=over 4
381 517
387C<AnyEvent::Impl:xxx> modules, but can be any other class in the case 523C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
388AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 524AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
389 525
390The known classes so far are: 526The known classes so far are:
391 527
392 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
393 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
394 AnyEvent::Impl::EV based on EV (an interface to libev, best choice). 528 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
395 AnyEvent::Impl::Event based on Event, second best choice. 529 AnyEvent::Impl::Event based on Event, second best choice.
530 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
396 AnyEvent::Impl::Glib based on Glib, third-best choice. 531 AnyEvent::Impl::Glib based on Glib, third-best choice.
397 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
398 AnyEvent::Impl::Tk based on Tk, very bad choice. 532 AnyEvent::Impl::Tk based on Tk, very bad choice.
399 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs). 533 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
400 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 534 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
401 AnyEvent::Impl::POE based on POE, not generic enough for full support. 535 AnyEvent::Impl::POE based on POE, not generic enough for full support.
402 536
415Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 549Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
416if necessary. You should only call this function right before you would 550if necessary. You should only call this function right before you would
417have created an AnyEvent watcher anyway, that is, as late as possible at 551have created an AnyEvent watcher anyway, that is, as late as possible at
418runtime. 552runtime.
419 553
554=item $guard = AnyEvent::post_detect { BLOCK }
555
556Arranges for the code block to be executed as soon as the event model is
557autodetected (or immediately if this has already happened).
558
559If called in scalar or list context, then it creates and returns an object
560that automatically removes the callback again when it is destroyed. See
561L<Coro::BDB> for a case where this is useful.
562
563=item @AnyEvent::post_detect
564
565If there are any code references in this array (you can C<push> to it
566before or after loading AnyEvent), then they will called directly after
567the event loop has been chosen.
568
569You should check C<$AnyEvent::MODEL> before adding to this array, though:
570if it contains a true value then the event loop has already been detected,
571and the array will be ignored.
572
573Best use C<AnyEvent::post_detect { BLOCK }> instead.
574
420=back 575=back
421 576
422=head1 WHAT TO DO IN A MODULE 577=head1 WHAT TO DO IN A MODULE
423 578
424As a module author, you should C<use AnyEvent> and call AnyEvent methods 579As a module author, you should C<use AnyEvent> and call AnyEvent methods
428decide which event module to use as soon as the first method is called, so 583decide which event module to use as soon as the first method is called, so
429by calling AnyEvent in your module body you force the user of your module 584by calling AnyEvent in your module body you force the user of your module
430to load the event module first. 585to load the event module first.
431 586
432Never call C<< ->wait >> on a condition variable unless you I<know> that 587Never call C<< ->wait >> on a condition variable unless you I<know> that
433the C<< ->broadcast >> method has been called on it already. This is 588the C<< ->send >> method has been called on it already. This is
434because it will stall the whole program, and the whole point of using 589because it will stall the whole program, and the whole point of using
435events is to stay interactive. 590events is to stay interactive.
436 591
437It is fine, however, to call C<< ->wait >> when the user of your module 592It is fine, however, to call C<< ->wait >> when the user of your module
438requests it (i.e. if you create a http request object ad have a method 593requests it (i.e. if you create a http request object ad have a method
458 613
459You can chose to use a rather inefficient pure-perl implementation by 614You can chose to use a rather inefficient pure-perl implementation by
460loading the C<AnyEvent::Impl::Perl> module, which gives you similar 615loading the C<AnyEvent::Impl::Perl> module, which gives you similar
461behaviour everywhere, but letting AnyEvent chose is generally better. 616behaviour everywhere, but letting AnyEvent chose is generally better.
462 617
618=head1 OTHER MODULES
619
620The following is a non-exhaustive list of additional modules that use
621AnyEvent and can therefore be mixed easily with other AnyEvent modules
622in the same program. Some of the modules come with AnyEvent, some are
623available via CPAN.
624
625=over 4
626
627=item L<AnyEvent::Util>
628
629Contains various utility functions that replace often-used but blocking
630functions such as C<inet_aton> by event-/callback-based versions.
631
632=item L<AnyEvent::Handle>
633
634Provide read and write buffers and manages watchers for reads and writes.
635
636=item L<AnyEvent::HTTPD>
637
638Provides a simple web application server framework.
639
640=item L<AnyEvent::DNS>
641
642Provides asynchronous DNS resolver capabilities, beyond what
643L<AnyEvent::Util> offers.
644
645=item L<AnyEvent::FastPing>
646
647The fastest ping in the west.
648
649=item L<Net::IRC3>
650
651AnyEvent based IRC client module family.
652
653=item L<Net::XMPP2>
654
655AnyEvent based XMPP (Jabber protocol) module family.
656
657=item L<Net::FCP>
658
659AnyEvent-based implementation of the Freenet Client Protocol, birthplace
660of AnyEvent.
661
662=item L<Event::ExecFlow>
663
664High level API for event-based execution flow control.
665
666=item L<Coro>
667
668Has special support for AnyEvent via L<Coro::AnyEvent>.
669
670=item L<AnyEvent::AIO>, L<IO::AIO>
671
672Truly asynchronous I/O, should be in the toolbox of every event
673programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
674together.
675
676=item L<AnyEvent::BDB>, L<BDB>
677
678Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently fuses
679IO::AIO and AnyEvent together.
680
681=item L<IO::Lambda>
682
683The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
684
685=back
686
463=cut 687=cut
464 688
465package AnyEvent; 689package AnyEvent;
466 690
467no warnings; 691no warnings;
468use strict; 692use strict;
469 693
470use Carp; 694use Carp;
471 695
472our $VERSION = '3.3'; 696our $VERSION = '3.4';
473our $MODEL; 697our $MODEL;
474 698
475our $AUTOLOAD; 699our $AUTOLOAD;
476our @ISA; 700our @ISA;
477 701
478our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 702our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
479 703
480our @REGISTRY; 704our @REGISTRY;
481 705
482my @models = ( 706my @models = (
483 [Coro::EV:: => AnyEvent::Impl::CoroEV::],
484 [Coro::Event:: => AnyEvent::Impl::CoroEvent::],
485 [EV:: => AnyEvent::Impl::EV::], 707 [EV:: => AnyEvent::Impl::EV::],
486 [Event:: => AnyEvent::Impl::Event::], 708 [Event:: => AnyEvent::Impl::Event::],
487 [Glib:: => AnyEvent::Impl::Glib::],
488 [Tk:: => AnyEvent::Impl::Tk::], 709 [Tk:: => AnyEvent::Impl::Tk::],
489 [Wx:: => AnyEvent::Impl::POE::], 710 [Wx:: => AnyEvent::Impl::POE::],
490 [Prima:: => AnyEvent::Impl::POE::], 711 [Prima:: => AnyEvent::Impl::POE::],
491 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 712 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
492 # everything below here will not be autoprobed as the pureperl backend should work everywhere 713 # everything below here will not be autoprobed as the pureperl backend should work everywhere
714 [Glib:: => AnyEvent::Impl::Glib::],
493 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 715 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
494 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 716 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
495 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 717 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
496); 718);
497 719
498our %method = map +($_ => 1), qw(io timer signal child condvar broadcast wait one_event DESTROY); 720our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY);
721
722our @post_detect;
723
724sub post_detect(&) {
725 my ($cb) = @_;
726
727 if ($MODEL) {
728 $cb->();
729
730 1
731 } else {
732 push @post_detect, $cb;
733
734 defined wantarray
735 ? bless \$cb, "AnyEvent::Util::Guard"
736 : ()
737 }
738}
739
740sub AnyEvent::Util::Guard::DESTROY {
741 @post_detect = grep $_ != ${$_[0]}, @post_detect;
742}
499 743
500sub detect() { 744sub detect() {
501 unless ($MODEL) { 745 unless ($MODEL) {
502 no strict 'refs'; 746 no strict 'refs';
503 747
537 last; 781 last;
538 } 782 }
539 } 783 }
540 784
541 $MODEL 785 $MODEL
542 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV (or Coro+EV), Event (or Coro+Event) or Glib."; 786 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.";
543 } 787 }
544 } 788 }
545 789
546 unshift @ISA, $MODEL; 790 unshift @ISA, $MODEL;
547 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 791 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
792
793 (shift @post_detect)->() while @post_detect;
548 } 794 }
549 795
550 $MODEL 796 $MODEL
551} 797}
552 798
944 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1190 EV/EV 400000 244 0.56 0.46 0.31 EV native interface
945 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers 1191 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers
946 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal 1192 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal
947 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation 1193 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation
948 Event/Event 16000 516 31.88 31.30 0.85 Event native interface 1194 Event/Event 16000 516 31.88 31.30 0.85 Event native interface
949 Event/Any 16000 936 39.17 33.63 1.43 Event + AnyEvent watchers 1195 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers
950 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour 1196 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour
951 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers 1197 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers
952 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event 1198 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event
953 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select 1199 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select
954 1200
958well. For example, a select-based event loop (such as the pure perl one) 1204well. For example, a select-based event loop (such as the pure perl one)
959can never compete with an event loop that uses epoll when the number of 1205can never compete with an event loop that uses epoll when the number of
960file descriptors grows high. In this benchmark, all events become ready at 1206file descriptors grows high. In this benchmark, all events become ready at
961the same time, so select/poll-based implementations get an unnatural speed 1207the same time, so select/poll-based implementations get an unnatural speed
962boost. 1208boost.
1209
1210Also, note that the number of watchers usually has a nonlinear effect on
1211overall speed, that is, creating twice as many watchers doesn't take twice
1212the time - usually it takes longer. This puts event loops tested with a
1213higher number of watchers at a disadvantage.
1214
1215To put the range of results into perspective, consider that on the
1216benchmark machine, handling an event takes roughly 1600 CPU cycles with
1217EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 CPU
1218cycles with POE.
963 1219
964C<EV> is the sole leader regarding speed and memory use, which are both 1220C<EV> is the sole leader regarding speed and memory use, which are both
965maximal/minimal, respectively. Even when going through AnyEvent, it uses 1221maximal/minimal, respectively. Even when going through AnyEvent, it uses
966far less memory than any other event loop and is still faster than Event 1222far less memory than any other event loop and is still faster than Event
967natively. 1223natively.
990file descriptor is dup()ed for each watcher. This shows that the dup() 1246file descriptor is dup()ed for each watcher. This shows that the dup()
991employed by some adaptors is not a big performance issue (it does incur a 1247employed by some adaptors is not a big performance issue (it does incur a
992hidden memory cost inside the kernel which is not reflected in the figures 1248hidden memory cost inside the kernel which is not reflected in the figures
993above). 1249above).
994 1250
995C<POE>, regardless of underlying event loop (whether using its pure 1251C<POE>, regardless of underlying event loop (whether using its pure perl
996perl select-based backend or the Event module, the POE-EV backend 1252select-based backend or the Event module, the POE-EV backend couldn't
997couldn't be tested because it wasn't working) shows abysmal performance 1253be tested because it wasn't working) shows abysmal performance and
998and memory usage: Watchers use almost 30 times as much memory as 1254memory usage with AnyEvent: Watchers use almost 30 times as much memory
999EV watchers, and 10 times as much memory as Event (the high memory 1255as EV watchers, and 10 times as much memory as Event (the high memory
1000requirements are caused by requiring a session for each watcher). Watcher 1256requirements are caused by requiring a session for each watcher). Watcher
1001invocation speed is almost 900 times slower than with AnyEvent's pure perl 1257invocation speed is almost 900 times slower than with AnyEvent's pure perl
1258implementation.
1259
1002implementation. The design of the POE adaptor class in AnyEvent can not 1260The design of the POE adaptor class in AnyEvent can not really account
1003really account for this, as session creation overhead is small compared 1261for the performance issues, though, as session creation overhead is
1004to execution of the state machine, which is coded pretty optimally within 1262small compared to execution of the state machine, which is coded pretty
1005L<AnyEvent::Impl::POE>. POE simply seems to be abysmally slow. 1263optimally within L<AnyEvent::Impl::POE> (and while everybody agrees that
1264using multiple sessions is not a good approach, especially regarding
1265memory usage, even the author of POE could not come up with a faster
1266design).
1006 1267
1007=head3 Summary 1268=head3 Summary
1008 1269
1009=over 4 1270=over 4
1010 1271
1043distribution. 1304distribution.
1044 1305
1045=head3 Explanation of the columns 1306=head3 Explanation of the columns
1046 1307
1047I<sockets> is the number of sockets, and twice the number of "servers" (as 1308I<sockets> is the number of sockets, and twice the number of "servers" (as
1048eahc server has a read and write socket end). 1309each server has a read and write socket end).
1049 1310
1050I<create> is the time it takes to create a socketpair (which is 1311I<create> is the time it takes to create a socketpair (which is
1051nontrivial) and two watchers: an I/O watcher and a timeout watcher. 1312nontrivial) and two watchers: an I/O watcher and a timeout watcher.
1052 1313
1053I<request>, the most important value, is the time it takes to handle a 1314I<request>, the most important value, is the time it takes to handle a
1057 1318
1058=head3 Results 1319=head3 Results
1059 1320
1060 name sockets create request 1321 name sockets create request
1061 EV 20000 69.01 11.16 1322 EV 20000 69.01 11.16
1062 Perl 20000 75.28 112.76 1323 Perl 20000 73.32 35.87
1063 Event 20000 212.62 257.32 1324 Event 20000 212.62 257.32
1064 Glib 20000 651.16 1896.30 1325 Glib 20000 651.16 1896.30
1065 POE 20000 349.67 12317.24 uses POE::Loop::Event 1326 POE 20000 349.67 12317.24 uses POE::Loop::Event
1066 1327
1067=head3 Discussion 1328=head3 Discussion
1089 1350
1090=head3 Summary 1351=head3 Summary
1091 1352
1092=over 4 1353=over 4
1093 1354
1094=item * The pure perl implementation performs extremely well, considering 1355=item * The pure perl implementation performs extremely well.
1095that it uses select.
1096 1356
1097=item * Avoid Glib or POE in large projects where performance matters. 1357=item * Avoid Glib or POE in large projects where performance matters.
1098 1358
1099=back 1359=back
1100 1360
1113 1373
1114=head3 Results 1374=head3 Results
1115 1375
1116 name sockets create request 1376 name sockets create request
1117 EV 16 20.00 6.54 1377 EV 16 20.00 6.54
1378 Perl 16 25.75 12.62
1118 Event 16 81.27 35.86 1379 Event 16 81.27 35.86
1119 Glib 16 32.63 15.48 1380 Glib 16 32.63 15.48
1120 Perl 16 24.62 162.37
1121 POE 16 261.87 276.28 uses POE::Loop::Event 1381 POE 16 261.87 276.28 uses POE::Loop::Event
1122 1382
1123=head3 Discussion 1383=head3 Discussion
1124 1384
1125The benchmark tries to test the performance of a typical small 1385The benchmark tries to test the performance of a typical small
1126server. While knowing how various event loops perform is interesting, keep 1386server. While knowing how various event loops perform is interesting, keep
1127in mind that their overhead in this case is usually not as important, due 1387in mind that their overhead in this case is usually not as important, due
1128to the small absolute number of watchers. 1388to the small absolute number of watchers (that is, you need efficiency and
1389speed most when you have lots of watchers, not when you only have a few of
1390them).
1129 1391
1130EV is again fastest. 1392EV is again fastest.
1131 1393
1132The C-based event loops Event and Glib come in second this time, as the 1394Perl again comes second. It is noticably faster than the C-based event
1133overhead of running an iteration is much smaller in C than in Perl (little 1395loops Event and Glib, although the difference is too small to really
1134code to execute in the inner loop, and perl's function calling overhead is 1396matter.
1135high, and updating all the data structures is costly).
1136 1397
1137The pure perl event loop is much slower, but still competitive.
1138
1139POE also performs much better in this case, but is is stillf ar behind the 1398POE also performs much better in this case, but is is still far behind the
1140others. 1399others.
1141 1400
1142=head3 Summary 1401=head3 Summary
1143 1402
1144=over 4 1403=over 4
1150 1409
1151 1410
1152=head1 FORK 1411=head1 FORK
1153 1412
1154Most event libraries are not fork-safe. The ones who are usually are 1413Most event libraries are not fork-safe. The ones who are usually are
1155because they are so inefficient. Only L<EV> is fully fork-aware. 1414because they rely on inefficient but fork-safe C<select> or C<poll>
1415calls. Only L<EV> is fully fork-aware.
1156 1416
1157If you have to fork, you must either do so I<before> creating your first 1417If you have to fork, you must either do so I<before> creating your first
1158watcher OR you must not use AnyEvent at all in the child. 1418watcher OR you must not use AnyEvent at all in the child.
1159 1419
1160 1420
1172 1432
1173 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1433 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1174 1434
1175 use AnyEvent; 1435 use AnyEvent;
1176 1436
1437Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1438be used to probe what backend is used and gain other information (which is
1439probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1440
1177 1441
1178=head1 SEE ALSO 1442=head1 SEE ALSO
1179 1443
1180Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, 1444Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>,
1181L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>,
1182L<Event::Lib>, L<Qt>, L<POE>. 1445L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
1183 1446
1184Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, 1447Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
1185L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, 1448L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
1186L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>, 1449L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
1187L<AnyEvent::Impl::Qt>, L<AnyEvent::Impl::POE>. 1450L<AnyEvent::Impl::POE>.
1451
1452Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>,
1188 1453
1189Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1454Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
1190 1455
1191 1456
1192=head1 AUTHOR 1457=head1 AUTHOR

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines