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.109 by root, Sat May 10 00:45:18 2008 UTC vs.
Revision 1.128 by root, Sat May 24 02:50:45 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).
… …
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
… …
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-robbin 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
… …
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
… …
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 suppporting 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 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
560that automatically removes the callback again when it is destroyed. See
561L<Coro::BDB> for a case where this is useful.
562
559=item @AnyEvent::on_detect 563=item @AnyEvent::post_detect
560 564
561If 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
562before or after loading AnyEvent), then they will called directly after 566before or after loading AnyEvent), then they will called directly after
563the event loop has been chosen. 567the event loop has been chosen.
564 568
565You should check C<$AnyEvent::MODEL> before adding to this array, though: 569You should check C<$AnyEvent::MODEL> before adding to this array, though:
566if 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,
567and the array will be ignored. 571and the array will be ignored.
568 572
569Best use C<AnyEvent::on_detect { BLOCK }> instead. 573Best use C<AnyEvent::post_detect { BLOCK }> instead.
570 574
571=back 575=back
572 576
573=head1 WHAT TO DO IN A MODULE 577=head1 WHAT TO DO IN A MODULE
574 578
… …
578Be careful when you create watchers in the module body - AnyEvent will 582Be careful when you create watchers in the module body - AnyEvent will
579decide 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
580by 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
581to load the event module first. 585to load the event module first.
582 586
583Never 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
584the C<< ->send >> method has been called on it already. This is 588the C<< ->send >> method has been called on it already. This is
585because 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
586events is to stay interactive. 590events is to stay interactive.
587 591
588It 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
589requests 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
590called C<results> that returns the results, it should call C<< ->wait >> 594called C<results> that returns the results, it should call C<< ->recv >>
591freely, 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).
592 596
593=head1 WHAT TO DO IN THE MAIN PROGRAM 597=head1 WHAT TO DO IN THE MAIN PROGRAM
594 598
595There 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
… …
629 633
630Provide read and write buffers and manages watchers for reads and writes. 634Provide read and write buffers and manages watchers for reads and writes.
631 635
632=item L<AnyEvent::Socket> 636=item L<AnyEvent::Socket>
633 637
634Provides 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.
635 641
636=item L<AnyEvent::HTTPD> 642=item L<AnyEvent::HTTPD>
637 643
638Provides a simple web application server framework. 644Provides a simple web application server framework.
639 645
640=item L<AnyEvent::DNS> 646=item L<AnyEvent::DNS>
641 647
642Provides asynchronous DNS resolver capabilities, beyond what 648Provides rich asynchronous DNS resolver capabilities.
643L<AnyEvent::Util> offers.
644 649
645=item L<AnyEvent::FastPing> 650=item L<AnyEvent::FastPing>
646 651
647The fastest ping in the west. 652The fastest ping in the west.
648 653
… …
665 670
666=item L<Coro> 671=item L<Coro>
667 672
668Has special support for AnyEvent via L<Coro::AnyEvent>. 673Has special support for AnyEvent via L<Coro::AnyEvent>.
669 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
670=item L<IO::Lambda> 686=item L<IO::Lambda>
671 687
672The 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.
673
674=item L<IO::AIO>
675
676Truly asynchronous I/O, should be in the toolbox of every event
677programmer. Can be trivially made to use AnyEvent.
678
679=item L<BDB>
680
681Truly asynchronous Berkeley DB access. Can be trivially made to use
682AnyEvent.
683 689
684=back 690=back
685 691
686=cut 692=cut
687 693
… …
690no warnings; 696no warnings;
691use strict; 697use strict;
692 698
693use Carp; 699use Carp;
694 700
695our $VERSION = '3.4'; 701our $VERSION = '3.6';
696our $MODEL; 702our $MODEL;
697 703
698our $AUTOLOAD; 704our $AUTOLOAD;
699our @ISA; 705our @ISA;
700 706
701our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 707our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
702 708
703our @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}
704 718
705my @models = ( 719my @models = (
706 [EV:: => AnyEvent::Impl::EV::], 720 [EV:: => AnyEvent::Impl::EV::],
707 [Event:: => AnyEvent::Impl::Event::], 721 [Event:: => AnyEvent::Impl::Event::],
708 [Tk:: => AnyEvent::Impl::Tk::], 722 [Tk:: => AnyEvent::Impl::Tk::],
… …
716 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 730 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
717); 731);
718 732
719our %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);
720 734
721our @on_detect; 735our @post_detect;
722 736
723sub on_detect(&) { 737sub post_detect(&) {
738 my ($cb) = @_;
739
724 if ($MODEL) { 740 if ($MODEL) {
725 $_[0]->(); 741 $cb->();
742
743 1
726 } else { 744 } else {
727 push @on_detect, $_[0]; 745 push @post_detect, $cb;
746
747 defined wantarray
748 ? bless \$cb, "AnyEvent::Util::PostDetect"
749 : ()
728 } 750 }
751}
752
753sub AnyEvent::Util::PostDetect::DESTROY {
754 @post_detect = grep $_ != ${$_[0]}, @post_detect;
729} 755}
730 756
731sub detect() { 757sub detect() {
732 unless ($MODEL) { 758 unless ($MODEL) {
733 no strict 'refs'; 759 no strict 'refs';
… …
775 } 801 }
776 802
777 unshift @ISA, $MODEL; 803 unshift @ISA, $MODEL;
778 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 804 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
779 805
780 (shift @on_detect)->() while @on_detect; 806 (shift @post_detect)->() while @post_detect;
781 } 807 }
782 808
783 $MODEL 809 $MODEL
784} 810}
785 811
… …
795 $class->$func (@_); 821 $class->$func (@_);
796} 822}
797 823
798package AnyEvent::Base; 824package AnyEvent::Base;
799 825
800# default implementation for ->condvar, ->wait, ->broadcast 826# default implementation for ->condvar
801 827
802sub condvar { 828sub condvar {
803 bless \my $flag, "AnyEvent::Base::CondVar" 829 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
804}
805
806sub AnyEvent::Base::CondVar::broadcast {
807 ${$_[0]}++;
808}
809
810sub AnyEvent::Base::CondVar::wait {
811 AnyEvent->one_event while !${$_[0]};
812} 830}
813 831
814# default implementation for ->signal 832# default implementation for ->signal
815 833
816our %SIG_CB; 834our %SIG_CB;
… …
890 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} }; 908 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
891 909
892 undef $CHLD_W unless keys %PID_CB; 910 undef $CHLD_W unless keys %PID_CB;
893} 911}
894 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
895=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 969=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
896 970
897This 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
898a 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
899provide AnyEvent compatibility. 973provide AnyEvent compatibility.
… …
955model it chooses. 1029model it chooses.
956 1030
957=item C<PERL_ANYEVENT_MODEL> 1031=item C<PERL_ANYEVENT_MODEL>
958 1032
959This 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
960autodetection and -probing kicks in. It must be a string consisting 1034auto detection and -probing kicks in. It must be a string consisting
961entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended 1035entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
962and 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,
963used 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
964autodetection and -probing. 1038auto detection and -probing.
965 1039
966This functionality might change in future versions. 1040This functionality might change in future versions.
967 1041
968For 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
969could start your program like this: 1043could start your program like this:
970 1044
971 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.
972 1077
973=back 1078=back
974 1079
975=head1 EXAMPLE PROGRAM 1080=head1 EXAMPLE PROGRAM
976 1081
… …
987 poll => 'r', 1092 poll => 'r',
988 cb => sub { 1093 cb => sub {
989 warn "io event <$_[0]>\n"; # will always output <r> 1094 warn "io event <$_[0]>\n"; # will always output <r>
990 chomp (my $input = <STDIN>); # read a line 1095 chomp (my $input = <STDIN>); # read a line
991 warn "read: $input\n"; # output what has been read 1096 warn "read: $input\n"; # output what has been read
992 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 1097 $cv->send if $input =~ /^q/i; # quit program if /^q/i
993 }, 1098 },
994 ); 1099 );
995 1100
996 my $time_watcher; # can only be used once 1101 my $time_watcher; # can only be used once
997 1102
… …
1002 }); 1107 });
1003 } 1108 }
1004 1109
1005 new_timer; # create first timer 1110 new_timer; # create first timer
1006 1111
1007 $cv->wait; # wait until user enters /^q/i 1112 $cv->recv; # wait until user enters /^q/i
1008 1113
1009=head1 REAL-WORLD EXAMPLE 1114=head1 REAL-WORLD EXAMPLE
1010 1115
1011Consider the L<Net::FCP> module. It features (among others) the following 1116Consider the L<Net::FCP> module. It features (among others) the following
1012API 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:
… …
1062 syswrite $txn->{fh}, $txn->{request} 1167 syswrite $txn->{fh}, $txn->{request}
1063 or die "connection or write error"; 1168 or die "connection or write error";
1064 $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 });
1065 1170
1066Again, 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
1067result and signals any possible waiters that the request ahs finished: 1172result and signals any possible waiters that the request has finished:
1068 1173
1069 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 1174 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
1070 1175
1071 if (end-of-file or data complete) { 1176 if (end-of-file or data complete) {
1072 $txn->{result} = $txn->{buf}; 1177 $txn->{result} = $txn->{buf};
1073 $txn->{finished}->broadcast; 1178 $txn->{finished}->send;
1074 $txb->{cb}->($txn) of $txn->{cb}; # also call callback 1179 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
1075 } 1180 }
1076 1181
1077The 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
1078request 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
1079data: 1184data:
1080 1185
1081 $txn->{finished}->wait; 1186 $txn->{finished}->recv;
1082 return $txn->{result}; 1187 return $txn->{result};
1083 1188
1084The 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)
1085that occured during request processing. The C<result> method detects 1190that occurred during request processing. The C<result> method detects
1086whether an exception as thrown (it is stored inside the $txn object) 1191whether an exception as thrown (it is stored inside the $txn object)
1087and just throws the exception, which means connection errors and other 1192and just throws the exception, which means connection errors and other
1088problems 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
1089random callback. 1194random callback.
1090 1195
… …
1121 1226
1122 my $quit = AnyEvent->condvar; 1227 my $quit = AnyEvent->condvar;
1123 1228
1124 $fcp->txn_client_get ($url)->cb (sub { 1229 $fcp->txn_client_get ($url)->cb (sub {
1125 ... 1230 ...
1126 $quit->broadcast; 1231 $quit->send;
1127 }); 1232 });
1128 1233
1129 $quit->wait; 1234 $quit->recv;
1130 1235
1131 1236
1132=head1 BENCHMARKS 1237=head1 BENCHMARKS
1133 1238
1134To 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
… …
1136of various event loops I prepared some benchmarks. 1241of various event loops I prepared some benchmarks.
1137 1242
1138=head2 BENCHMARKING ANYEVENT OVERHEAD 1243=head2 BENCHMARKING ANYEVENT OVERHEAD
1139 1244
1140Here is a benchmark of various supported event models used natively and 1245Here is a benchmark of various supported event models used natively and
1141through anyevent. The benchmark creates a lot of timers (with a zero 1246through AnyEvent. The benchmark creates a lot of timers (with a zero
1142timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 1247timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
1143which it is), lets them fire exactly once and destroys them again. 1248which it is), lets them fire exactly once and destroys them again.
1144 1249
1145Source 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
1146distribution. 1251distribution.
… …
1163all watchers, to avoid adding memory overhead. That means closure creation 1268all watchers, to avoid adding memory overhead. That means closure creation
1164and memory usage is not included in the figures. 1269and memory usage is not included in the figures.
1165 1270
1166I<invoke> is the time, in microseconds, used to invoke a simple 1271I<invoke> is the time, in microseconds, used to invoke a simple
1167callback. 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
1168invoked "watcher" times, it would C<< ->broadcast >> a condvar once to 1273invoked "watcher" times, it would C<< ->send >> a condvar once to
1169signal the end of this phase. 1274signal the end of this phase.
1170 1275
1171I<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
1172watcher. 1277watcher.
1173 1278
… …
1269 1374
1270=back 1375=back
1271 1376
1272=head2 BENCHMARKING THE LARGE SERVER CASE 1377=head2 BENCHMARKING THE LARGE SERVER CASE
1273 1378
1274This benchmark atcually benchmarks the event loop itself. It works by 1379This benchmark actually benchmarks the event loop itself. It works by
1275creating a number of "servers": each server consists of a socketpair, a 1380creating a number of "servers": each server consists of a socket pair, a
1276timeout 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
1277watcher 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
1278watcher 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".
1279 1384
1280The 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
1281are 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
1282fds 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
1283timeout is reset each time something is read because that reflects how 1388timeout is reset each time something is read because that reflects how
1284most timeouts work (and puts extra pressure on the event loops). 1389most timeouts work (and puts extra pressure on the event loops).
1285 1390
1286In this benchmark, we use 10000 socketpairs (20000 sockets), of which 100 1391In this benchmark, we use 10000 socket pairs (20000 sockets), of which 100
1287(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
1288connections, most of which are idle at any one point in time. 1393connections, most of which are idle at any one point in time.
1289 1394
1290Source 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
1291distribution. 1396distribution.
… …
1293=head3 Explanation of the columns 1398=head3 Explanation of the columns
1294 1399
1295I<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
1296each server has a read and write socket end). 1401each server has a read and write socket end).
1297 1402
1298I<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
1299nontrivial) and two watchers: an I/O watcher and a timeout watcher. 1404nontrivial) and two watchers: an I/O watcher and a timeout watcher.
1300 1405
1301I<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
1302single "request", that is, reading the token from the pipe and forwarding 1407single "request", that is, reading the token from the pipe and forwarding
1303it to another server. This includes deleting the old timeout and creating 1408it to another server. This includes deleting the old timeout and creating
… …
1426probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1531probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1427 1532
1428 1533
1429=head1 SEE ALSO 1534=head1 SEE ALSO
1430 1535
1536Utility functions: L<AnyEvent::Util>.
1537
1431Event 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>,
1432L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 1539L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
1433 1540
1434Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 1541Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
1435L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 1542L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
1436L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 1543L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
1437L<AnyEvent::Impl::POE>. 1544L<AnyEvent::Impl::POE>.
1438 1545
1546Non-blocking file handles, sockets, TCP clients and
1547servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>.
1548
1549Asynchronous DNS: L<AnyEvent::DNS>.
1550
1439Coroutine 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>,
1440 1552
1441Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1553Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1442 1554
1443 1555
1444=head1 AUTHOR 1556=head1 AUTHOR
1445 1557
1446 Marc Lehmann <schmorp@schmorp.de> 1558 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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