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.110 by root, Sat May 10 00:57:31 2008 UTC vs.
Revision 1.129 by elmex, Sat May 24 15:19:30 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, 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
… …
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->send; # wake up current and all future recv's
20 $w->wait; # enters "main loop" till $condvar gets ->send 21 $w->recv; # enters "main loop" till $condvar gets ->send
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?
… …
57as those use one of the supported event loops. It is trivial to add new 57as those use one of the supported event loops. It is trivial to add new
58event loops to AnyEvent, too, so it is future-proof). 58event loops to AnyEvent, too, so it is future-proof).
59 59
60In addition to being free of having to use I<the one and only true event 60In addition to being free of having to use I<the one and only true event
61model>, AnyEvent also is free of bloat and policy: with POE or similar 61model>, AnyEvent also is free of bloat and policy: with POE or similar
62modules, you get an enourmous amount of code and strict rules you have to 62modules, you get an enormous amount of code and strict rules you have to
63follow. AnyEvent, on the other hand, is lean and up to the point, by only 63follow. AnyEvent, on the other hand, is lean and up to the point, by only
64offering the functionality that is necessary, in as thin as a wrapper as 64offering the functionality that is necessary, in as thin as a wrapper as
65technically possible. 65technically possible.
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
… …
108 108
109=head1 WATCHERS 109=head1 WATCHERS
110 110
111AnyEvent has the central concept of a I<watcher>, which is an object that 111AnyEvent has the central concept of a I<watcher>, which is an object that
112stores relevant data for each kind of event you are waiting for, such as 112stores relevant data for each kind of event you are waiting for, such as
113the callback to call, the filehandle to watch, etc. 113the callback to call, the file handle to watch, etc.
114 114
115These watchers are normal Perl objects with normal Perl lifetime. After 115These watchers are normal Perl objects with normal Perl lifetime. After
116creating a watcher it will immediately "watch" for events and invoke the 116creating a watcher it will immediately "watch" for events and invoke the
117callback when the event occurs (of course, only when the event model 117callback when the event occurs (of course, only when the event model
118is in control). 118is in control).
… …
237 237
238Although the callback might get passed parameters, their value and 238Although the callback might get passed parameters, their value and
239presence is undefined and you cannot rely on them. Portable AnyEvent 239presence is undefined and you cannot rely on them. Portable AnyEvent
240callbacks cannot use arguments passed to signal watcher callbacks. 240callbacks cannot use arguments passed to signal watcher callbacks.
241 241
242Multiple signal occurances can be clumped together into one callback 242Multiple signal occurrences can be clumped together into one callback
243invocation, and callback invocation will be synchronous. synchronous means 243invocation, and callback invocation will be synchronous. Synchronous means
244that it might take a while until the signal gets handled by the process, 244that it might take a while until the signal gets handled by the process,
245but it is guarenteed not to interrupt any other callbacks. 245but it is guaranteed not to interrupt any other callbacks.
246 246
247The main advantage of using these watchers is that you can share a signal 247The main advantage of using these watchers is that you can share a signal
248between multiple watchers. 248between multiple watchers.
249 249
250This watcher might use C<%SIG>, so programs overwriting those signals 250This watcher might use C<%SIG>, so programs overwriting those signals
… …
278C<fork> the child (alternatively, you can call C<AnyEvent::detect>). 278C<fork> the child (alternatively, you can call C<AnyEvent::detect>).
279 279
280Example: fork a process and wait for it 280Example: fork a process and wait for it
281 281
282 my $done = AnyEvent->condvar; 282 my $done = AnyEvent->condvar;
283
284 AnyEvent::detect; # force event module to be initialised
285 283
286 my $pid = fork or exit 5; 284 my $pid = fork or exit 5;
287 285
288 my $w = AnyEvent->child ( 286 my $w = AnyEvent->child (
289 pid => $pid, 287 pid => $pid,
… …
293 $done->send; 291 $done->send;
294 }, 292 },
295 ); 293 );
296 294
297 # do something else, then wait for process exit 295 # do something else, then wait for process exit
298 $done->wait; 296 $done->recv;
299 297
300=head2 CONDITION VARIABLES 298=head2 CONDITION VARIABLES
301 299
302If you are familiar with some event loops you will know that all of them 300If 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 301require you to run some blocking "loop", "run" or similar function that
… …
312Condition variables can be created by calling the C<< AnyEvent->condvar 310Condition variables can be created by calling the C<< AnyEvent->condvar
313>> method, usually without arguments. The only argument pair allowed is 311>> method, usually without arguments. The only argument pair allowed is
314C<cb>, which specifies a callback to be called when the condition variable 312C<cb>, which specifies a callback to be called when the condition variable
315becomes true. 313becomes true.
316 314
317After creation, the conditon variable is "false" until it becomes "true" 315After creation, the condition variable is "false" until it becomes "true"
318by calling the C<send> method. 316by calling the C<send> method.
319 317
320Condition variables are similar to callbacks, except that you can 318Condition variables are similar to callbacks, except that you can
321optionally wait for them. They can also be called merge points - points 319optionally wait for them. They can also be called merge points - points
322in time where multiple outstandign events have been processed. And yet 320in time where multiple outstanding events have been processed. And yet
323another way to call them is transations - each condition variable can be 321another way to call them is transactions - each condition variable can be
324used to represent a transaction, which finishes at some point and delivers 322used to represent a transaction, which finishes at some point and delivers
325a result. 323a result.
326 324
327Condition variables are very useful to signal that something has finished, 325Condition variables are very useful to signal that something has finished,
328for example, if you write a module that does asynchronous http requests, 326for example, if you write a module that does asynchronous http requests,
329then a condition variable would be the ideal candidate to signal the 327then a condition variable would be the ideal candidate to signal the
330availability of results. The user can either act when the callback is 328availability of results. The user can either act when the callback is
331called or can synchronously C<< ->wait >> for the results. 329called or can synchronously C<< ->recv >> for the results.
332 330
333You can also use them to simulate traditional event loops - for example, 331You can also use them to simulate traditional event loops - for example,
334you can block your main program until an event occurs - for example, you 332you can block your main program until an event occurs - for example, you
335could C<< ->wait >> in your main program until the user clicks the Quit 333could C<< ->recv >> in your main program until the user clicks the Quit
336button of your app, which would C<< ->send >> the "quit" event. 334button of your app, which would C<< ->send >> the "quit" event.
337 335
338Note that condition variables recurse into the event loop - if you have 336Note that condition variables recurse into the event loop - if you have
339two pieces of code that call C<< ->wait >> in a round-robbin fashion, you 337two pieces of code that call C<< ->recv >> in a round-robin fashion, you
340lose. Therefore, condition variables are good to export to your caller, but 338lose. Therefore, condition variables are good to export to your caller, but
341you should avoid making a blocking wait yourself, at least in callbacks, 339you should avoid making a blocking wait yourself, at least in callbacks,
342as this asks for trouble. 340as this asks for trouble.
343 341
344Condition variables are represented by hash refs in perl, and the keys 342Condition variables are represented by hash refs in perl, and the keys
… …
365 cb => sub { $result_ready->send }, 363 cb => sub { $result_ready->send },
366 ); 364 );
367 365
368 # this "blocks" (while handling events) till the callback 366 # this "blocks" (while handling events) till the callback
369 # calls send 367 # calls send
370 $result_ready->wait; 368 $result_ready->recv;
371 369
372=head3 METHODS FOR PRODUCERS 370=head3 METHODS FOR PRODUCERS
373 371
374These methods should only be used by the producing side, i.e. the 372These methods should only be used by the producing side, i.e. the
375code/module that eventually sends the signal. Note that it is also 373code/module that eventually sends the signal. Note that it is also
… …
378 376
379=over 4 377=over 4
380 378
381=item $cv->send (...) 379=item $cv->send (...)
382 380
383Flag the condition as ready - a running C<< ->wait >> and all further 381Flag the condition as ready - a running C<< ->recv >> and all further
384calls to C<wait> will (eventually) return after this method has been 382calls to C<recv> will (eventually) return after this method has been
385called. If nobody is waiting the send will be remembered. 383called. If nobody is waiting the send will be remembered.
386 384
387If a callback has been set on the condition variable, it is called 385If a callback has been set on the condition variable, it is called
388immediately from within send. 386immediately from within send.
389 387
390Any arguments passed to the C<send> call will be returned by all 388Any arguments passed to the C<send> call will be returned by all
391future C<< ->wait >> calls. 389future C<< ->recv >> calls.
392 390
393=item $cv->croak ($error) 391=item $cv->croak ($error)
394 392
395Similar to send, but causes all call's wait C<< ->wait >> to invoke 393Similar to send, but causes all call's to C<< ->recv >> to invoke
396C<Carp::croak> with the given error message/object/scalar. 394C<Carp::croak> with the given error message/object/scalar.
397 395
398This can be used to signal any errors to the condition variable 396This can be used to signal any errors to the condition variable
399user/consumer. 397user/consumer.
400 398
401=item $cv->begin ([group callback]) 399=item $cv->begin ([group callback])
402 400
403=item $cv->end 401=item $cv->end
402
403These two methods are EXPERIMENTAL and MIGHT CHANGE.
404 404
405These two methods can be used to combine many transactions/events into 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 406one. For example, a function that pings many hosts in parallel might want
407to use a condition variable for the whole process. 407to use a condition variable for the whole process.
408 408
… …
443doesn't execute once). 443doesn't execute once).
444 444
445This is the general pattern when you "fan out" into multiple subrequests: 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> 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 447is called at least once, and then, for each subrequest you start, call
448C<begin> and for eahc subrequest you finish, call C<end>. 448C<begin> and for each subrequest you finish, call C<end>.
449 449
450=back 450=back
451 451
452=head3 METHODS FOR CONSUMERS 452=head3 METHODS FOR CONSUMERS
453 453
454These methods should only be used by the consuming side, i.e. the 454These methods should only be used by the consuming side, i.e. the
455code awaits the condition. 455code awaits the condition.
456 456
457=over 4 457=over 4
458 458
459=item $cv->wait 459=item $cv->recv
460 460
461Wait (blocking if necessary) until the C<< ->send >> or C<< ->croak 461Wait (blocking if necessary) until the C<< ->send >> or C<< ->croak
462>> methods have been called on c<$cv>, while servicing other watchers 462>> methods have been called on c<$cv>, while servicing other watchers
463normally. 463normally.
464 464
… …
475(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
476using 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
477caller 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
478condition variables with some kind of request results and supporting 478condition variables with some kind of request results and supporting
479callbacks so the caller knows that getting the result will not block, 479callbacks so the caller knows that getting the result will not block,
480while still suppporting blocking waits if the caller so desires). 480while still supporting blocking waits if the caller so desires).
481 481
482Another reason I<never> to C<< ->wait >> in a module is that you cannot 482Another reason I<never> to C<< ->recv >> in a module is that you cannot
483sensibly have two C<< ->wait >>'s in parallel, as that would require 483sensibly have two C<< ->recv >>'s in parallel, as that would require
484multiple interpreters or coroutines/threads, none of which C<AnyEvent> 484multiple interpreters or coroutines/threads, none of which C<AnyEvent>
485can supply. 485can supply.
486 486
487The L<Coro> module, however, I<can> and I<does> supply coroutines and, in 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 488fact, L<Coro::AnyEvent> replaces AnyEvent's condvars by coroutine-safe
489versions and also integrates coroutines into AnyEvent, making blocking 489versions and also integrates coroutines into AnyEvent, making blocking
490C<< ->wait >> calls perfectly safe as long as they are done from another 490C<< ->recv >> calls perfectly safe as long as they are done from another
491coroutine (one that doesn't run the event loop). 491coroutine (one that doesn't run the event loop).
492 492
493You can ensure that C<< -wait >> never blocks by setting a callback and 493You can ensure that C<< -recv >> never blocks by setting a callback and
494only calling C<< ->wait >> from within that callback (or at a later 494only calling C<< ->recv >> from within that callback (or at a later
495time). This will work even when the event loop does not support blocking 495time). This will work even when the event loop does not support blocking
496waits otherwise. 496waits otherwise.
497 497
498=item $bool = $cv->ready 498=item $bool = $cv->ready
499 499
… …
504 504
505This is a mutator function that returns the callback set and optionally 505This is a mutator function that returns the callback set and optionally
506replaces it before doing so. 506replaces it before doing so.
507 507
508The callback will be called when the condition becomes "true", i.e. when 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 509C<send> or C<croak> are called. Calling C<recv> inside the callback
510or at any later time is guaranteed not to block. 510or at any later time is guaranteed not to block.
511 511
512=back 512=back
513 513
514=head1 GLOBAL VARIABLES AND FUNCTIONS 514=head1 GLOBAL VARIABLES AND FUNCTIONS
… …
549Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 549Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
550if necessary. You should only call this function right before you would 550if necessary. You should only call this function right before you would
551have 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
552runtime. 552runtime.
553 553
554=item $guard = AnyEvent::on_detect { BLOCK } 554=item $guard = AnyEvent::post_detect { BLOCK }
555 555
556Arranges for the code block to be executed as soon as the event model is 556Arranges for the code block to be executed as soon as the event model is
557autodetected (or immediately if this has already happened). 557autodetected (or immediately if this has already happened).
558 558
559If called in scalar or list context, then it creates and returns an object 559If called in scalar or list context, then it creates and returns an object
560that automatically removes the callback again when it is destroyed. 560that automatically removes the callback again when it is destroyed. See
561L<Coro::BDB> for a case where this is useful.
561 562
562=item @AnyEvent::on_detect 563=item @AnyEvent::post_detect
563 564
564If there are any code references in this array (you can C<push> to it 565If there are any code references in this array (you can C<push> to it
565before or after loading AnyEvent), then they will called directly after 566before or after loading AnyEvent), then they will called directly after
566the event loop has been chosen. 567the event loop has been chosen.
567 568
568You should check C<$AnyEvent::MODEL> before adding to this array, though: 569You should check C<$AnyEvent::MODEL> before adding to this array, though:
569if it contains a true value then the event loop has already been detected, 570if it contains a true value then the event loop has already been detected,
570and the array will be ignored. 571and the array will be ignored.
571 572
572Best use C<AnyEvent::on_detect { BLOCK }> instead. 573Best use C<AnyEvent::post_detect { BLOCK }> instead.
573 574
574=back 575=back
575 576
576=head1 WHAT TO DO IN A MODULE 577=head1 WHAT TO DO IN A MODULE
577 578
… …
581Be careful when you create watchers in the module body - AnyEvent will 582Be careful when you create watchers in the module body - AnyEvent will
582decide 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
583by 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
584to load the event module first. 585to load the event module first.
585 586
586Never call C<< ->wait >> on a condition variable unless you I<know> that 587Never call C<< ->recv >> on a condition variable unless you I<know> that
587the C<< ->send >> method has been called on it already. This is 588the C<< ->send >> method has been called on it already. This is
588because 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
589events is to stay interactive. 590events is to stay interactive.
590 591
591It is fine, however, to call C<< ->wait >> when the user of your module 592It is fine, however, to call C<< ->recv >> when the user of your module
592requests 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
593called C<results> that returns the results, it should call C<< ->wait >> 594called C<results> that returns the results, it should call C<< ->recv >>
594freely, as the user of your module knows what she is doing. always). 595freely, as the user of your module knows what she is doing. always).
595 596
596=head1 WHAT TO DO IN THE MAIN PROGRAM 597=head1 WHAT TO DO IN THE MAIN PROGRAM
597 598
598There will always be a single main program - the only place that should 599There will always be a single main program - the only place that should
… …
632 633
633Provide read and write buffers and manages watchers for reads and writes. 634Provide read and write buffers and manages watchers for reads and writes.
634 635
635=item L<AnyEvent::Socket> 636=item L<AnyEvent::Socket>
636 637
637Provides a means to do non-blocking connects, accepts etc. 638Provides various utility functions for (internet protocol) sockets,
639addresses and name resolution. Also functions to create non-blocking tcp
640connections or tcp servers, with IPv6 and SRV record support and more.
638 641
639=item L<AnyEvent::HTTPD> 642=item L<AnyEvent::HTTPD>
640 643
641Provides a simple web application server framework. 644Provides a simple web application server framework.
642 645
643=item L<AnyEvent::DNS> 646=item L<AnyEvent::DNS>
644 647
645Provides asynchronous DNS resolver capabilities, beyond what 648Provides rich asynchronous DNS resolver capabilities.
646L<AnyEvent::Util> offers.
647 649
648=item L<AnyEvent::FastPing> 650=item L<AnyEvent::FastPing>
649 651
650The fastest ping in the west. 652The fastest ping in the west.
651 653
… …
668 670
669=item L<Coro> 671=item L<Coro>
670 672
671Has special support for AnyEvent via L<Coro::AnyEvent>. 673Has special support for AnyEvent via L<Coro::AnyEvent>.
672 674
675=item L<AnyEvent::AIO>, L<IO::AIO>
676
677Truly asynchronous I/O, should be in the toolbox of every event
678programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
679together.
680
681=item L<AnyEvent::BDB>, L<BDB>
682
683Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently fuses
684IO::AIO and AnyEvent together.
685
673=item L<IO::Lambda> 686=item L<IO::Lambda>
674 687
675The lambda approach to I/O - don't ask, look there. Can use AnyEvent. 688The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
676
677=item L<IO::AIO>
678
679Truly asynchronous I/O, should be in the toolbox of every event
680programmer. Can be trivially made to use AnyEvent.
681
682=item L<BDB>
683
684Truly asynchronous Berkeley DB access. Can be trivially made to use
685AnyEvent.
686 689
687=back 690=back
688 691
689=cut 692=cut
690 693
… …
693no warnings; 696no warnings;
694use strict; 697use strict;
695 698
696use Carp; 699use Carp;
697 700
698our $VERSION = '3.4'; 701our $VERSION = '3.6';
699our $MODEL; 702our $MODEL;
700 703
701our $AUTOLOAD; 704our $AUTOLOAD;
702our @ISA; 705our @ISA;
703 706
704our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 707our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
705 708
706our @REGISTRY; 709our @REGISTRY;
710
711our %PROTOCOL; # (ipv4|ipv6) => (1|2)
712
713{
714 my $idx;
715 $PROTOCOL{$_} = ++$idx
716 for split /\s*,\s*/, $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
717}
707 718
708my @models = ( 719my @models = (
709 [EV:: => AnyEvent::Impl::EV::], 720 [EV:: => AnyEvent::Impl::EV::],
710 [Event:: => AnyEvent::Impl::Event::], 721 [Event:: => AnyEvent::Impl::Event::],
711 [Tk:: => AnyEvent::Impl::Tk::], 722 [Tk:: => AnyEvent::Impl::Tk::],
… …
719 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 730 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
720); 731);
721 732
722our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); 733our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY);
723 734
724our @on_detect; 735our @post_detect;
725 736
726sub on_detect(&) { 737sub post_detect(&) {
727 my ($cb) = @_; 738 my ($cb) = @_;
728 739
729 if ($MODEL) { 740 if ($MODEL) {
730 $cb->(); 741 $cb->();
731 742
732 1 743 1
733 } else { 744 } else {
734 push @on_detect, $cb; 745 push @post_detect, $cb;
735 746
736 defined wantarray 747 defined wantarray
737 ? bless \$cb, "AnyEvent::Util::Guard" 748 ? bless \$cb, "AnyEvent::Util::PostDetect"
738 : () 749 : ()
739 } 750 }
740} 751}
741 752
742sub AnyEvent::Util::Guard::DESTROY { 753sub AnyEvent::Util::PostDetect::DESTROY {
743 @on_detect = grep $_ != ${$_[0]}, @on_detect; 754 @post_detect = grep $_ != ${$_[0]}, @post_detect;
744} 755}
745 756
746sub detect() { 757sub detect() {
747 unless ($MODEL) { 758 unless ($MODEL) {
748 no strict 'refs'; 759 no strict 'refs';
… …
790 } 801 }
791 802
792 unshift @ISA, $MODEL; 803 unshift @ISA, $MODEL;
793 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 804 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
794 805
795 (shift @on_detect)->() while @on_detect; 806 (shift @post_detect)->() while @post_detect;
796 } 807 }
797 808
798 $MODEL 809 $MODEL
799} 810}
800 811
… …
810 $class->$func (@_); 821 $class->$func (@_);
811} 822}
812 823
813package AnyEvent::Base; 824package AnyEvent::Base;
814 825
815# default implementation for ->condvar, ->wait, ->broadcast 826# default implementation for ->condvar
816 827
817sub condvar { 828sub condvar {
818 bless \my $flag, "AnyEvent::Base::CondVar" 829 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
819}
820
821sub AnyEvent::Base::CondVar::broadcast {
822 ${$_[0]}++;
823}
824
825sub AnyEvent::Base::CondVar::wait {
826 AnyEvent->one_event while !${$_[0]};
827} 830}
828 831
829# default implementation for ->signal 832# default implementation for ->signal
830 833
831our %SIG_CB; 834our %SIG_CB;
… …
905 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} }; 908 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
906 909
907 undef $CHLD_W unless keys %PID_CB; 910 undef $CHLD_W unless keys %PID_CB;
908} 911}
909 912
913package AnyEvent::CondVar;
914
915our @ISA = AnyEvent::CondVar::Base::;
916
917package AnyEvent::CondVar::Base;
918
919sub _send {
920 # nop
921}
922
923sub send {
924 my $cv = shift;
925 $cv->{_ae_sent} = [@_];
926 (delete $cv->{_ae_cb})->($cv) if $cv->{_ae_cb};
927 $cv->_send;
928}
929
930sub croak {
931 $_[0]{_ae_croak} = $_[1];
932 $_[0]->send;
933}
934
935sub ready {
936 $_[0]{_ae_sent}
937}
938
939sub _wait {
940 AnyEvent->one_event while !$_[0]{_ae_sent};
941}
942
943sub recv {
944 $_[0]->_wait;
945
946 Carp::croak $_[0]{_ae_croak} if $_[0]{_ae_croak};
947 wantarray ? @{ $_[0]{_ae_sent} } : $_[0]{_ae_sent}[0]
948}
949
950sub cb {
951 $_[0]{_ae_cb} = $_[1] if @_ > 1;
952 $_[0]{_ae_cb}
953}
954
955sub begin {
956 ++$_[0]{_ae_counter};
957 $_[0]{_ae_end_cb} = $_[1] if @_ > 1;
958}
959
960sub end {
961 return if --$_[0]{_ae_counter};
962 &{ $_[0]{_ae_end_cb} || sub { $_[0]->send } };
963}
964
965# undocumented/compatibility with pre-3.4
966*broadcast = \&send;
967*wait = \&_wait;
968
910=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 969=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
911 970
912This is an advanced topic that you do not normally need to use AnyEvent in 971This is an advanced topic that you do not normally need to use AnyEvent in
913a module. This section is only of use to event loop authors who want to 972a module. This section is only of use to event loop authors who want to
914provide AnyEvent compatibility. 973provide AnyEvent compatibility.
… …
970model it chooses. 1029model it chooses.
971 1030
972=item C<PERL_ANYEVENT_MODEL> 1031=item C<PERL_ANYEVENT_MODEL>
973 1032
974This can be used to specify the event model to be used by AnyEvent, before 1033This can be used to specify the event model to be used by AnyEvent, before
975autodetection and -probing kicks in. It must be a string consisting 1034auto detection and -probing kicks in. It must be a string consisting
976entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended 1035entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
977and the resulting module name is loaded and if the load was successful, 1036and the resulting module name is loaded and if the load was successful,
978used as event model. If it fails to load AnyEvent will proceed with 1037used as event model. If it fails to load AnyEvent will proceed with
979autodetection and -probing. 1038auto detection and -probing.
980 1039
981This functionality might change in future versions. 1040This functionality might change in future versions.
982 1041
983For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you 1042For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
984could start your program like this: 1043could start your program like this:
985 1044
986 PERL_ANYEVENT_MODEL=Perl perl ... 1045 PERL_ANYEVENT_MODEL=Perl perl ...
1046
1047=item C<PERL_ANYEVENT_PROTOCOLS>
1048
1049Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1050for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1051of auto probing).
1052
1053Must be set to a comma-separated list of protocols or address families,
1054current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1055used, and preference will be given to protocols mentioned earlier in the
1056list.
1057
1058This variable can effectively be used for denial-of-service attacks
1059against local programs (e.g. when setuid), although the impact is likely
1060small, as the program has to handle connection errors already-
1061
1062Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1063but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1064- only support IPv4, never try to resolve or contact IPv6
1065addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1066IPv6, but prefer IPv6 over IPv4.
1067
1068=item C<PERL_ANYEVENT_EDNS0>
1069
1070Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
1071for DNS. This extension is generally useful to reduce DNS traffic, but
1072some (broken) firewalls drop such DNS packets, which is why it is off by
1073default.
1074
1075Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1076EDNS0 in its DNS requests.
987 1077
988=back 1078=back
989 1079
990=head1 EXAMPLE PROGRAM 1080=head1 EXAMPLE PROGRAM
991 1081
… …
1002 poll => 'r', 1092 poll => 'r',
1003 cb => sub { 1093 cb => sub {
1004 warn "io event <$_[0]>\n"; # will always output <r> 1094 warn "io event <$_[0]>\n"; # will always output <r>
1005 chomp (my $input = <STDIN>); # read a line 1095 chomp (my $input = <STDIN>); # read a line
1006 warn "read: $input\n"; # output what has been read 1096 warn "read: $input\n"; # output what has been read
1007 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 1097 $cv->send if $input =~ /^q/i; # quit program if /^q/i
1008 }, 1098 },
1009 ); 1099 );
1010 1100
1011 my $time_watcher; # can only be used once 1101 my $time_watcher; # can only be used once
1012 1102
… …
1017 }); 1107 });
1018 } 1108 }
1019 1109
1020 new_timer; # create first timer 1110 new_timer; # create first timer
1021 1111
1022 $cv->wait; # wait until user enters /^q/i 1112 $cv->recv; # wait until user enters /^q/i
1023 1113
1024=head1 REAL-WORLD EXAMPLE 1114=head1 REAL-WORLD EXAMPLE
1025 1115
1026Consider the L<Net::FCP> module. It features (among others) the following 1116Consider the L<Net::FCP> module. It features (among others) the following
1027API calls, which are to freenet what HTTP GET requests are to http: 1117API calls, which are to freenet what HTTP GET requests are to http:
… …
1077 syswrite $txn->{fh}, $txn->{request} 1167 syswrite $txn->{fh}, $txn->{request}
1078 or die "connection or write error"; 1168 or die "connection or write error";
1079 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r }); 1169 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r });
1080 1170
1081Again, C<fh_ready_r> waits till all data has arrived, and then stores the 1171Again, C<fh_ready_r> waits till all data has arrived, and then stores the
1082result and signals any possible waiters that the request ahs finished: 1172result and signals any possible waiters that the request has finished:
1083 1173
1084 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 1174 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
1085 1175
1086 if (end-of-file or data complete) { 1176 if (end-of-file or data complete) {
1087 $txn->{result} = $txn->{buf}; 1177 $txn->{result} = $txn->{buf};
1088 $txn->{finished}->broadcast; 1178 $txn->{finished}->send;
1089 $txb->{cb}->($txn) of $txn->{cb}; # also call callback 1179 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
1090 } 1180 }
1091 1181
1092The C<result> method, finally, just waits for the finished signal (if the 1182The C<result> method, finally, just waits for the finished signal (if the
1093request was already finished, it doesn't wait, of course, and returns the 1183request was already finished, it doesn't wait, of course, and returns the
1094data: 1184data:
1095 1185
1096 $txn->{finished}->wait; 1186 $txn->{finished}->recv;
1097 return $txn->{result}; 1187 return $txn->{result};
1098 1188
1099The actual code goes further and collects all errors (C<die>s, exceptions) 1189The actual code goes further and collects all errors (C<die>s, exceptions)
1100that occured during request processing. The C<result> method detects 1190that occurred during request processing. The C<result> method detects
1101whether an exception as thrown (it is stored inside the $txn object) 1191whether an exception as thrown (it is stored inside the $txn object)
1102and just throws the exception, which means connection errors and other 1192and just throws the exception, which means connection errors and other
1103problems get reported tot he code that tries to use the result, not in a 1193problems get reported tot he code that tries to use the result, not in a
1104random callback. 1194random callback.
1105 1195
… …
1136 1226
1137 my $quit = AnyEvent->condvar; 1227 my $quit = AnyEvent->condvar;
1138 1228
1139 $fcp->txn_client_get ($url)->cb (sub { 1229 $fcp->txn_client_get ($url)->cb (sub {
1140 ... 1230 ...
1141 $quit->broadcast; 1231 $quit->send;
1142 }); 1232 });
1143 1233
1144 $quit->wait; 1234 $quit->recv;
1145 1235
1146 1236
1147=head1 BENCHMARKS 1237=head1 BENCHMARKS
1148 1238
1149To give you an idea of the performance and overheads that AnyEvent adds 1239To give you an idea of the performance and overheads that AnyEvent adds
… …
1151of various event loops I prepared some benchmarks. 1241of various event loops I prepared some benchmarks.
1152 1242
1153=head2 BENCHMARKING ANYEVENT OVERHEAD 1243=head2 BENCHMARKING ANYEVENT OVERHEAD
1154 1244
1155Here is a benchmark of various supported event models used natively and 1245Here is a benchmark of various supported event models used natively and
1156through anyevent. The benchmark creates a lot of timers (with a zero 1246through AnyEvent. The benchmark creates a lot of timers (with a zero
1157timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 1247timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
1158which it is), lets them fire exactly once and destroys them again. 1248which it is), lets them fire exactly once and destroys them again.
1159 1249
1160Source code for this benchmark is found as F<eg/bench> in the AnyEvent 1250Source code for this benchmark is found as F<eg/bench> in the AnyEvent
1161distribution. 1251distribution.
… …
1178all watchers, to avoid adding memory overhead. That means closure creation 1268all watchers, to avoid adding memory overhead. That means closure creation
1179and memory usage is not included in the figures. 1269and memory usage is not included in the figures.
1180 1270
1181I<invoke> is the time, in microseconds, used to invoke a simple 1271I<invoke> is the time, in microseconds, used to invoke a simple
1182callback. The callback simply counts down a Perl variable and after it was 1272callback. The callback simply counts down a Perl variable and after it was
1183invoked "watcher" times, it would C<< ->broadcast >> a condvar once to 1273invoked "watcher" times, it would C<< ->send >> a condvar once to
1184signal the end of this phase. 1274signal the end of this phase.
1185 1275
1186I<destroy> is the time, in microseconds, that it takes to destroy a single 1276I<destroy> is the time, in microseconds, that it takes to destroy a single
1187watcher. 1277watcher.
1188 1278
… …
1284 1374
1285=back 1375=back
1286 1376
1287=head2 BENCHMARKING THE LARGE SERVER CASE 1377=head2 BENCHMARKING THE LARGE SERVER CASE
1288 1378
1289This benchmark atcually benchmarks the event loop itself. It works by 1379This benchmark actually benchmarks the event loop itself. It works by
1290creating a number of "servers": each server consists of a socketpair, a 1380creating a number of "servers": each server consists of a socket pair, a
1291timeout watcher that gets reset on activity (but never fires), and an I/O 1381timeout watcher that gets reset on activity (but never fires), and an I/O
1292watcher waiting for input on one side of the socket. Each time the socket 1382watcher waiting for input on one side of the socket. Each time the socket
1293watcher reads a byte it will write that byte to a random other "server". 1383watcher reads a byte it will write that byte to a random other "server".
1294 1384
1295The effect is that there will be a lot of I/O watchers, only part of which 1385The effect is that there will be a lot of I/O watchers, only part of which
1296are active at any one point (so there is a constant number of active 1386are active at any one point (so there is a constant number of active
1297fds for each loop iterstaion, but which fds these are is random). The 1387fds for each loop iteration, but which fds these are is random). The
1298timeout is reset each time something is read because that reflects how 1388timeout is reset each time something is read because that reflects how
1299most timeouts work (and puts extra pressure on the event loops). 1389most timeouts work (and puts extra pressure on the event loops).
1300 1390
1301In this benchmark, we use 10000 socketpairs (20000 sockets), of which 100 1391In this benchmark, we use 10000 socket pairs (20000 sockets), of which 100
1302(1%) are active. This mirrors the activity of large servers with many 1392(1%) are active. This mirrors the activity of large servers with many
1303connections, most of which are idle at any one point in time. 1393connections, most of which are idle at any one point in time.
1304 1394
1305Source code for this benchmark is found as F<eg/bench2> in the AnyEvent 1395Source code for this benchmark is found as F<eg/bench2> in the AnyEvent
1306distribution. 1396distribution.
… …
1308=head3 Explanation of the columns 1398=head3 Explanation of the columns
1309 1399
1310I<sockets> is the number of sockets, and twice the number of "servers" (as 1400I<sockets> is the number of sockets, and twice the number of "servers" (as
1311each server has a read and write socket end). 1401each server has a read and write socket end).
1312 1402
1313I<create> is the time it takes to create a socketpair (which is 1403I<create> is the time it takes to create a socket pair (which is
1314nontrivial) and two watchers: an I/O watcher and a timeout watcher. 1404nontrivial) and two watchers: an I/O watcher and a timeout watcher.
1315 1405
1316I<request>, the most important value, is the time it takes to handle a 1406I<request>, the most important value, is the time it takes to handle a
1317single "request", that is, reading the token from the pipe and forwarding 1407single "request", that is, reading the token from the pipe and forwarding
1318it to another server. This includes deleting the old timeout and creating 1408it to another server. This includes deleting the old timeout and creating
… …
1391speed most when you have lots of watchers, not when you only have a few of 1481speed most when you have lots of watchers, not when you only have a few of
1392them). 1482them).
1393 1483
1394EV is again fastest. 1484EV is again fastest.
1395 1485
1396Perl again comes second. It is noticably faster than the C-based event 1486Perl again comes second. It is noticeably faster than the C-based event
1397loops Event and Glib, although the difference is too small to really 1487loops Event and Glib, although the difference is too small to really
1398matter. 1488matter.
1399 1489
1400POE also performs much better in this case, but is is still far behind the 1490POE also performs much better in this case, but is is still far behind the
1401others. 1491others.
… …
1441probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1531probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1442 1532
1443 1533
1444=head1 SEE ALSO 1534=head1 SEE ALSO
1445 1535
1536Utility functions: L<AnyEvent::Util>.
1537
1446Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>, 1538Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>,
1447L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 1539L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
1448 1540
1449Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 1541Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
1450L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 1542L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
1451L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 1543L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
1452L<AnyEvent::Impl::POE>. 1544L<AnyEvent::Impl::POE>.
1453 1545
1546Non-blocking file handles, sockets, TCP clients and
1547servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>.
1548
1549Asynchronous DNS: L<AnyEvent::DNS>.
1550
1454Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>, 1551Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>,
1455 1552
1456Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1553Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1457 1554
1458 1555
1459=head1 AUTHOR 1556=head1 AUTHOR
1460 1557
1461 Marc Lehmann <schmorp@schmorp.de> 1558 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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