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.112 by root, Sat May 10 01:04:42 2008 UTC vs.
Revision 1.131 by root, Sat May 24 17:48:38 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 (or calling the condition variable as if it
317were a callback).
319 318
320Condition variables are similar to callbacks, except that you can 319Condition variables are similar to callbacks, except that you can
321optionally wait for them. They can also be called merge points - points 320optionally wait for them. They can also be called merge points - points
322in time where multiple outstandign events have been processed. And yet 321in time where multiple outstanding events have been processed. And yet
323another way to call them is transations - each condition variable can be 322another way to call them is transactions - each condition variable can be
324used to represent a transaction, which finishes at some point and delivers 323used to represent a transaction, which finishes at some point and delivers
325a result. 324a result.
326 325
327Condition variables are very useful to signal that something has finished, 326Condition variables are very useful to signal that something has finished,
328for example, if you write a module that does asynchronous http requests, 327for example, if you write a module that does asynchronous http requests,
329then a condition variable would be the ideal candidate to signal the 328then a condition variable would be the ideal candidate to signal the
330availability of results. The user can either act when the callback is 329availability of results. The user can either act when the callback is
331called or can synchronously C<< ->wait >> for the results. 330called or can synchronously C<< ->recv >> for the results.
332 331
333You can also use them to simulate traditional event loops - for example, 332You can also use them to simulate traditional event loops - for example,
334you can block your main program until an event occurs - for example, you 333you 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 334could C<< ->recv >> in your main program until the user clicks the Quit
336button of your app, which would C<< ->send >> the "quit" event. 335button of your app, which would C<< ->send >> the "quit" event.
337 336
338Note that condition variables recurse into the event loop - if you have 337Note 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 338two 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 339lose. Therefore, condition variables are good to export to your caller, but
341you should avoid making a blocking wait yourself, at least in callbacks, 340you should avoid making a blocking wait yourself, at least in callbacks,
342as this asks for trouble. 341as this asks for trouble.
343 342
344Condition variables are represented by hash refs in perl, and the keys 343Condition variables are represented by hash refs in perl, and the keys
349 348
350There are two "sides" to a condition variable - the "producer side" which 349There are two "sides" to a condition variable - the "producer side" which
351eventually calls C<< -> send >>, and the "consumer side", which waits 350eventually calls C<< -> send >>, and the "consumer side", which waits
352for the send to occur. 351for the send to occur.
353 352
354Example: 353Example: wait for a timer.
355 354
356 # wait till the result is ready 355 # wait till the result is ready
357 my $result_ready = AnyEvent->condvar; 356 my $result_ready = AnyEvent->condvar;
358 357
359 # do something such as adding a timer 358 # do something such as adding a timer
365 cb => sub { $result_ready->send }, 364 cb => sub { $result_ready->send },
366 ); 365 );
367 366
368 # this "blocks" (while handling events) till the callback 367 # this "blocks" (while handling events) till the callback
369 # calls send 368 # calls send
370 $result_ready->wait; 369 $result_ready->recv;
370
371Example: wait for a timer, but take advantage of the fact that
372condition variables are also code references.
373
374 my $done = AnyEvent->condvar;
375 my $delay = AnyEvent->timer (after => 5, cb => $done);
376 $done->recv;
371 377
372=head3 METHODS FOR PRODUCERS 378=head3 METHODS FOR PRODUCERS
373 379
374These methods should only be used by the producing side, i.e. the 380These methods should only be used by the producing side, i.e. the
375code/module that eventually sends the signal. Note that it is also 381code/module that eventually sends the signal. Note that it is also
378 384
379=over 4 385=over 4
380 386
381=item $cv->send (...) 387=item $cv->send (...)
382 388
383Flag the condition as ready - a running C<< ->wait >> and all further 389Flag the condition as ready - a running C<< ->recv >> and all further
384calls to C<wait> will (eventually) return after this method has been 390calls to C<recv> will (eventually) return after this method has been
385called. If nobody is waiting the send will be remembered. 391called. If nobody is waiting the send will be remembered.
386 392
387If a callback has been set on the condition variable, it is called 393If a callback has been set on the condition variable, it is called
388immediately from within send. 394immediately from within send.
389 395
390Any arguments passed to the C<send> call will be returned by all 396Any arguments passed to the C<send> call will be returned by all
391future C<< ->wait >> calls. 397future C<< ->recv >> calls.
398
399Condition variables are overloaded so one can call them directly (as a
400code reference). Calling them directly is the same as calling C<send>.
392 401
393=item $cv->croak ($error) 402=item $cv->croak ($error)
394 403
395Similar to send, but causes all call's wait C<< ->wait >> to invoke 404Similar to send, but causes all call's to C<< ->recv >> to invoke
396C<Carp::croak> with the given error message/object/scalar. 405C<Carp::croak> with the given error message/object/scalar.
397 406
398This can be used to signal any errors to the condition variable 407This can be used to signal any errors to the condition variable
399user/consumer. 408user/consumer.
400 409
401=item $cv->begin ([group callback]) 410=item $cv->begin ([group callback])
402 411
403=item $cv->end 412=item $cv->end
413
414These two methods are EXPERIMENTAL and MIGHT CHANGE.
404 415
405These two methods can be used to combine many transactions/events into 416These two methods can be used to combine many transactions/events into
406one. For example, a function that pings many hosts in parallel might want 417one. For example, a function that pings many hosts in parallel might want
407to use a condition variable for the whole process. 418to use a condition variable for the whole process.
408 419
443doesn't execute once). 454doesn't execute once).
444 455
445This is the general pattern when you "fan out" into multiple subrequests: 456This 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> 457use 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 458is called at least once, and then, for each subrequest you start, call
448C<begin> and for eahc subrequest you finish, call C<end>. 459C<begin> and for each subrequest you finish, call C<end>.
449 460
450=back 461=back
451 462
452=head3 METHODS FOR CONSUMERS 463=head3 METHODS FOR CONSUMERS
453 464
454These methods should only be used by the consuming side, i.e. the 465These methods should only be used by the consuming side, i.e. the
455code awaits the condition. 466code awaits the condition.
456 467
457=over 4 468=over 4
458 469
459=item $cv->wait 470=item $cv->recv
460 471
461Wait (blocking if necessary) until the C<< ->send >> or C<< ->croak 472Wait (blocking if necessary) until the C<< ->send >> or C<< ->croak
462>> methods have been called on c<$cv>, while servicing other watchers 473>> methods have been called on c<$cv>, while servicing other watchers
463normally. 474normally.
464 475
475(programs might want to do that to stay interactive), so I<if you are 486(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 487using 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 488caller decide whether the call will block or not (for example, by coupling
478condition variables with some kind of request results and supporting 489condition variables with some kind of request results and supporting
479callbacks so the caller knows that getting the result will not block, 490callbacks so the caller knows that getting the result will not block,
480while still suppporting blocking waits if the caller so desires). 491while still supporting blocking waits if the caller so desires).
481 492
482Another reason I<never> to C<< ->wait >> in a module is that you cannot 493Another 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 494sensibly have two C<< ->recv >>'s in parallel, as that would require
484multiple interpreters or coroutines/threads, none of which C<AnyEvent> 495multiple interpreters or coroutines/threads, none of which C<AnyEvent>
485can supply. 496can supply.
486 497
487The L<Coro> module, however, I<can> and I<does> supply coroutines and, in 498The L<Coro> module, however, I<can> and I<does> supply coroutines and, in
488fact, L<Coro::AnyEvent> replaces AnyEvent's condvars by coroutine-safe 499fact, L<Coro::AnyEvent> replaces AnyEvent's condvars by coroutine-safe
489versions and also integrates coroutines into AnyEvent, making blocking 500versions and also integrates coroutines into AnyEvent, making blocking
490C<< ->wait >> calls perfectly safe as long as they are done from another 501C<< ->recv >> calls perfectly safe as long as they are done from another
491coroutine (one that doesn't run the event loop). 502coroutine (one that doesn't run the event loop).
492 503
493You can ensure that C<< -wait >> never blocks by setting a callback and 504You can ensure that C<< -recv >> never blocks by setting a callback and
494only calling C<< ->wait >> from within that callback (or at a later 505only calling C<< ->recv >> from within that callback (or at a later
495time). This will work even when the event loop does not support blocking 506time). This will work even when the event loop does not support blocking
496waits otherwise. 507waits otherwise.
497 508
498=item $bool = $cv->ready 509=item $bool = $cv->ready
499 510
504 515
505This is a mutator function that returns the callback set and optionally 516This is a mutator function that returns the callback set and optionally
506replaces it before doing so. 517replaces it before doing so.
507 518
508The callback will be called when the condition becomes "true", i.e. when 519The 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 520C<send> or C<croak> are called. Calling C<recv> inside the callback
510or at any later time is guaranteed not to block. 521or at any later time is guaranteed not to block.
511 522
512=back 523=back
513 524
514=head1 GLOBAL VARIABLES AND FUNCTIONS 525=head1 GLOBAL VARIABLES AND FUNCTIONS
582Be careful when you create watchers in the module body - AnyEvent will 593Be careful when you create watchers in the module body - AnyEvent will
583decide which event module to use as soon as the first method is called, so 594decide which event module to use as soon as the first method is called, so
584by calling AnyEvent in your module body you force the user of your module 595by calling AnyEvent in your module body you force the user of your module
585to load the event module first. 596to load the event module first.
586 597
587Never call C<< ->wait >> on a condition variable unless you I<know> that 598Never call C<< ->recv >> on a condition variable unless you I<know> that
588the C<< ->send >> method has been called on it already. This is 599the C<< ->send >> method has been called on it already. This is
589because it will stall the whole program, and the whole point of using 600because it will stall the whole program, and the whole point of using
590events is to stay interactive. 601events is to stay interactive.
591 602
592It is fine, however, to call C<< ->wait >> when the user of your module 603It is fine, however, to call C<< ->recv >> when the user of your module
593requests it (i.e. if you create a http request object ad have a method 604requests it (i.e. if you create a http request object ad have a method
594called C<results> that returns the results, it should call C<< ->wait >> 605called C<results> that returns the results, it should call C<< ->recv >>
595freely, as the user of your module knows what she is doing. always). 606freely, as the user of your module knows what she is doing. always).
596 607
597=head1 WHAT TO DO IN THE MAIN PROGRAM 608=head1 WHAT TO DO IN THE MAIN PROGRAM
598 609
599There will always be a single main program - the only place that should 610There will always be a single main program - the only place that should
633 644
634Provide read and write buffers and manages watchers for reads and writes. 645Provide read and write buffers and manages watchers for reads and writes.
635 646
636=item L<AnyEvent::Socket> 647=item L<AnyEvent::Socket>
637 648
638Provides a means to do non-blocking connects, accepts etc. 649Provides various utility functions for (internet protocol) sockets,
650addresses and name resolution. Also functions to create non-blocking tcp
651connections or tcp servers, with IPv6 and SRV record support and more.
639 652
640=item L<AnyEvent::HTTPD> 653=item L<AnyEvent::HTTPD>
641 654
642Provides a simple web application server framework. 655Provides a simple web application server framework.
643 656
644=item L<AnyEvent::DNS> 657=item L<AnyEvent::DNS>
645 658
646Provides asynchronous DNS resolver capabilities, beyond what 659Provides rich asynchronous DNS resolver capabilities.
647L<AnyEvent::Util> offers.
648 660
649=item L<AnyEvent::FastPing> 661=item L<AnyEvent::FastPing>
650 662
651The fastest ping in the west. 663The fastest ping in the west.
652 664
669 681
670=item L<Coro> 682=item L<Coro>
671 683
672Has special support for AnyEvent via L<Coro::AnyEvent>. 684Has special support for AnyEvent via L<Coro::AnyEvent>.
673 685
686=item L<AnyEvent::AIO>, L<IO::AIO>
687
688Truly asynchronous I/O, should be in the toolbox of every event
689programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
690together.
691
692=item L<AnyEvent::BDB>, L<BDB>
693
694Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently fuses
695IO::AIO and AnyEvent together.
696
674=item L<IO::Lambda> 697=item L<IO::Lambda>
675 698
676The lambda approach to I/O - don't ask, look there. Can use AnyEvent. 699The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
677
678=item L<IO::AIO>
679
680Truly asynchronous I/O, should be in the toolbox of every event
681programmer. Can be trivially made to use AnyEvent.
682
683=item L<BDB>
684
685Truly asynchronous Berkeley DB access. Can be trivially made to use
686AnyEvent.
687 700
688=back 701=back
689 702
690=cut 703=cut
691 704
694no warnings; 707no warnings;
695use strict; 708use strict;
696 709
697use Carp; 710use Carp;
698 711
699our $VERSION = '3.4'; 712our $VERSION = '4.0';
700our $MODEL; 713our $MODEL;
701 714
702our $AUTOLOAD; 715our $AUTOLOAD;
703our @ISA; 716our @ISA;
704 717
705our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 718our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
706 719
707our @REGISTRY; 720our @REGISTRY;
721
722our %PROTOCOL; # (ipv4|ipv6) => (1|2)
723
724{
725 my $idx;
726 $PROTOCOL{$_} = ++$idx
727 for split /\s*,\s*/, $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
728}
708 729
709my @models = ( 730my @models = (
710 [EV:: => AnyEvent::Impl::EV::], 731 [EV:: => AnyEvent::Impl::EV::],
711 [Event:: => AnyEvent::Impl::Event::], 732 [Event:: => AnyEvent::Impl::Event::],
712 [Tk:: => AnyEvent::Impl::Tk::], 733 [Tk:: => AnyEvent::Impl::Tk::],
733 1 754 1
734 } else { 755 } else {
735 push @post_detect, $cb; 756 push @post_detect, $cb;
736 757
737 defined wantarray 758 defined wantarray
738 ? bless \$cb, "AnyEvent::Util::Guard" 759 ? bless \$cb, "AnyEvent::Util::PostDetect"
739 : () 760 : ()
740 } 761 }
741} 762}
742 763
743sub AnyEvent::Util::Guard::DESTROY { 764sub AnyEvent::Util::PostDetect::DESTROY {
744 @post_detect = grep $_ != ${$_[0]}, @post_detect; 765 @post_detect = grep $_ != ${$_[0]}, @post_detect;
745} 766}
746 767
747sub detect() { 768sub detect() {
748 unless ($MODEL) { 769 unless ($MODEL) {
811 $class->$func (@_); 832 $class->$func (@_);
812} 833}
813 834
814package AnyEvent::Base; 835package AnyEvent::Base;
815 836
816# default implementation for ->condvar, ->wait, ->broadcast 837# default implementation for ->condvar
817 838
818sub condvar { 839sub condvar {
819 bless \my $flag, "AnyEvent::Base::CondVar" 840 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
820}
821
822sub AnyEvent::Base::CondVar::broadcast {
823 ${$_[0]}++;
824}
825
826sub AnyEvent::Base::CondVar::wait {
827 AnyEvent->one_event while !${$_[0]};
828} 841}
829 842
830# default implementation for ->signal 843# default implementation for ->signal
831 844
832our %SIG_CB; 845our %SIG_CB;
906 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} }; 919 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
907 920
908 undef $CHLD_W unless keys %PID_CB; 921 undef $CHLD_W unless keys %PID_CB;
909} 922}
910 923
924package AnyEvent::CondVar;
925
926our @ISA = AnyEvent::CondVar::Base::;
927
928package AnyEvent::CondVar::Base;
929
930use overload
931 '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
932 fallback => 1;
933
934sub _send {
935 # nop
936}
937
938sub send {
939 my $cv = shift;
940 $cv->{_ae_sent} = [@_];
941 (delete $cv->{_ae_cb})->($cv) if $cv->{_ae_cb};
942 $cv->_send;
943}
944
945sub croak {
946 $_[0]{_ae_croak} = $_[1];
947 $_[0]->send;
948}
949
950sub ready {
951 $_[0]{_ae_sent}
952}
953
954sub _wait {
955 AnyEvent->one_event while !$_[0]{_ae_sent};
956}
957
958sub recv {
959 $_[0]->_wait;
960
961 Carp::croak $_[0]{_ae_croak} if $_[0]{_ae_croak};
962 wantarray ? @{ $_[0]{_ae_sent} } : $_[0]{_ae_sent}[0]
963}
964
965sub cb {
966 $_[0]{_ae_cb} = $_[1] if @_ > 1;
967 $_[0]{_ae_cb}
968}
969
970sub begin {
971 ++$_[0]{_ae_counter};
972 $_[0]{_ae_end_cb} = $_[1] if @_ > 1;
973}
974
975sub end {
976 return if --$_[0]{_ae_counter};
977 &{ $_[0]{_ae_end_cb} || sub { $_[0]->send } };
978}
979
980# undocumented/compatibility with pre-3.4
981*broadcast = \&send;
982*wait = \&_wait;
983
911=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 984=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
912 985
913This is an advanced topic that you do not normally need to use AnyEvent in 986This is an advanced topic that you do not normally need to use AnyEvent in
914a module. This section is only of use to event loop authors who want to 987a module. This section is only of use to event loop authors who want to
915provide AnyEvent compatibility. 988provide AnyEvent compatibility.
971model it chooses. 1044model it chooses.
972 1045
973=item C<PERL_ANYEVENT_MODEL> 1046=item C<PERL_ANYEVENT_MODEL>
974 1047
975This can be used to specify the event model to be used by AnyEvent, before 1048This can be used to specify the event model to be used by AnyEvent, before
976autodetection and -probing kicks in. It must be a string consisting 1049auto detection and -probing kicks in. It must be a string consisting
977entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended 1050entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
978and the resulting module name is loaded and if the load was successful, 1051and the resulting module name is loaded and if the load was successful,
979used as event model. If it fails to load AnyEvent will proceed with 1052used as event model. If it fails to load AnyEvent will proceed with
980autodetection and -probing. 1053auto detection and -probing.
981 1054
982This functionality might change in future versions. 1055This functionality might change in future versions.
983 1056
984For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you 1057For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
985could start your program like this: 1058could start your program like this:
986 1059
987 PERL_ANYEVENT_MODEL=Perl perl ... 1060 PERL_ANYEVENT_MODEL=Perl perl ...
1061
1062=item C<PERL_ANYEVENT_PROTOCOLS>
1063
1064Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1065for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1066of auto probing).
1067
1068Must be set to a comma-separated list of protocols or address families,
1069current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1070used, and preference will be given to protocols mentioned earlier in the
1071list.
1072
1073This variable can effectively be used for denial-of-service attacks
1074against local programs (e.g. when setuid), although the impact is likely
1075small, as the program has to handle connection errors already-
1076
1077Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1078but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1079- only support IPv4, never try to resolve or contact IPv6
1080addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1081IPv6, but prefer IPv6 over IPv4.
1082
1083=item C<PERL_ANYEVENT_EDNS0>
1084
1085Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
1086for DNS. This extension is generally useful to reduce DNS traffic, but
1087some (broken) firewalls drop such DNS packets, which is why it is off by
1088default.
1089
1090Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1091EDNS0 in its DNS requests.
988 1092
989=back 1093=back
990 1094
991=head1 EXAMPLE PROGRAM 1095=head1 EXAMPLE PROGRAM
992 1096
1003 poll => 'r', 1107 poll => 'r',
1004 cb => sub { 1108 cb => sub {
1005 warn "io event <$_[0]>\n"; # will always output <r> 1109 warn "io event <$_[0]>\n"; # will always output <r>
1006 chomp (my $input = <STDIN>); # read a line 1110 chomp (my $input = <STDIN>); # read a line
1007 warn "read: $input\n"; # output what has been read 1111 warn "read: $input\n"; # output what has been read
1008 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 1112 $cv->send if $input =~ /^q/i; # quit program if /^q/i
1009 }, 1113 },
1010 ); 1114 );
1011 1115
1012 my $time_watcher; # can only be used once 1116 my $time_watcher; # can only be used once
1013 1117
1018 }); 1122 });
1019 } 1123 }
1020 1124
1021 new_timer; # create first timer 1125 new_timer; # create first timer
1022 1126
1023 $cv->wait; # wait until user enters /^q/i 1127 $cv->recv; # wait until user enters /^q/i
1024 1128
1025=head1 REAL-WORLD EXAMPLE 1129=head1 REAL-WORLD EXAMPLE
1026 1130
1027Consider the L<Net::FCP> module. It features (among others) the following 1131Consider the L<Net::FCP> module. It features (among others) the following
1028API calls, which are to freenet what HTTP GET requests are to http: 1132API calls, which are to freenet what HTTP GET requests are to http:
1078 syswrite $txn->{fh}, $txn->{request} 1182 syswrite $txn->{fh}, $txn->{request}
1079 or die "connection or write error"; 1183 or die "connection or write error";
1080 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r }); 1184 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r });
1081 1185
1082Again, C<fh_ready_r> waits till all data has arrived, and then stores the 1186Again, C<fh_ready_r> waits till all data has arrived, and then stores the
1083result and signals any possible waiters that the request ahs finished: 1187result and signals any possible waiters that the request has finished:
1084 1188
1085 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 1189 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
1086 1190
1087 if (end-of-file or data complete) { 1191 if (end-of-file or data complete) {
1088 $txn->{result} = $txn->{buf}; 1192 $txn->{result} = $txn->{buf};
1089 $txn->{finished}->broadcast; 1193 $txn->{finished}->send;
1090 $txb->{cb}->($txn) of $txn->{cb}; # also call callback 1194 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
1091 } 1195 }
1092 1196
1093The C<result> method, finally, just waits for the finished signal (if the 1197The C<result> method, finally, just waits for the finished signal (if the
1094request was already finished, it doesn't wait, of course, and returns the 1198request was already finished, it doesn't wait, of course, and returns the
1095data: 1199data:
1096 1200
1097 $txn->{finished}->wait; 1201 $txn->{finished}->recv;
1098 return $txn->{result}; 1202 return $txn->{result};
1099 1203
1100The actual code goes further and collects all errors (C<die>s, exceptions) 1204The actual code goes further and collects all errors (C<die>s, exceptions)
1101that occured during request processing. The C<result> method detects 1205that occurred during request processing. The C<result> method detects
1102whether an exception as thrown (it is stored inside the $txn object) 1206whether an exception as thrown (it is stored inside the $txn object)
1103and just throws the exception, which means connection errors and other 1207and just throws the exception, which means connection errors and other
1104problems get reported tot he code that tries to use the result, not in a 1208problems get reported tot he code that tries to use the result, not in a
1105random callback. 1209random callback.
1106 1210
1137 1241
1138 my $quit = AnyEvent->condvar; 1242 my $quit = AnyEvent->condvar;
1139 1243
1140 $fcp->txn_client_get ($url)->cb (sub { 1244 $fcp->txn_client_get ($url)->cb (sub {
1141 ... 1245 ...
1142 $quit->broadcast; 1246 $quit->send;
1143 }); 1247 });
1144 1248
1145 $quit->wait; 1249 $quit->recv;
1146 1250
1147 1251
1148=head1 BENCHMARKS 1252=head1 BENCHMARKS
1149 1253
1150To give you an idea of the performance and overheads that AnyEvent adds 1254To give you an idea of the performance and overheads that AnyEvent adds
1152of various event loops I prepared some benchmarks. 1256of various event loops I prepared some benchmarks.
1153 1257
1154=head2 BENCHMARKING ANYEVENT OVERHEAD 1258=head2 BENCHMARKING ANYEVENT OVERHEAD
1155 1259
1156Here is a benchmark of various supported event models used natively and 1260Here is a benchmark of various supported event models used natively and
1157through anyevent. The benchmark creates a lot of timers (with a zero 1261through AnyEvent. The benchmark creates a lot of timers (with a zero
1158timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 1262timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
1159which it is), lets them fire exactly once and destroys them again. 1263which it is), lets them fire exactly once and destroys them again.
1160 1264
1161Source code for this benchmark is found as F<eg/bench> in the AnyEvent 1265Source code for this benchmark is found as F<eg/bench> in the AnyEvent
1162distribution. 1266distribution.
1179all watchers, to avoid adding memory overhead. That means closure creation 1283all watchers, to avoid adding memory overhead. That means closure creation
1180and memory usage is not included in the figures. 1284and memory usage is not included in the figures.
1181 1285
1182I<invoke> is the time, in microseconds, used to invoke a simple 1286I<invoke> is the time, in microseconds, used to invoke a simple
1183callback. The callback simply counts down a Perl variable and after it was 1287callback. The callback simply counts down a Perl variable and after it was
1184invoked "watcher" times, it would C<< ->broadcast >> a condvar once to 1288invoked "watcher" times, it would C<< ->send >> a condvar once to
1185signal the end of this phase. 1289signal the end of this phase.
1186 1290
1187I<destroy> is the time, in microseconds, that it takes to destroy a single 1291I<destroy> is the time, in microseconds, that it takes to destroy a single
1188watcher. 1292watcher.
1189 1293
1285 1389
1286=back 1390=back
1287 1391
1288=head2 BENCHMARKING THE LARGE SERVER CASE 1392=head2 BENCHMARKING THE LARGE SERVER CASE
1289 1393
1290This benchmark atcually benchmarks the event loop itself. It works by 1394This benchmark actually benchmarks the event loop itself. It works by
1291creating a number of "servers": each server consists of a socketpair, a 1395creating a number of "servers": each server consists of a socket pair, a
1292timeout watcher that gets reset on activity (but never fires), and an I/O 1396timeout watcher that gets reset on activity (but never fires), and an I/O
1293watcher waiting for input on one side of the socket. Each time the socket 1397watcher waiting for input on one side of the socket. Each time the socket
1294watcher reads a byte it will write that byte to a random other "server". 1398watcher reads a byte it will write that byte to a random other "server".
1295 1399
1296The effect is that there will be a lot of I/O watchers, only part of which 1400The effect is that there will be a lot of I/O watchers, only part of which
1297are active at any one point (so there is a constant number of active 1401are active at any one point (so there is a constant number of active
1298fds for each loop iterstaion, but which fds these are is random). The 1402fds for each loop iteration, but which fds these are is random). The
1299timeout is reset each time something is read because that reflects how 1403timeout is reset each time something is read because that reflects how
1300most timeouts work (and puts extra pressure on the event loops). 1404most timeouts work (and puts extra pressure on the event loops).
1301 1405
1302In this benchmark, we use 10000 socketpairs (20000 sockets), of which 100 1406In this benchmark, we use 10000 socket pairs (20000 sockets), of which 100
1303(1%) are active. This mirrors the activity of large servers with many 1407(1%) are active. This mirrors the activity of large servers with many
1304connections, most of which are idle at any one point in time. 1408connections, most of which are idle at any one point in time.
1305 1409
1306Source code for this benchmark is found as F<eg/bench2> in the AnyEvent 1410Source code for this benchmark is found as F<eg/bench2> in the AnyEvent
1307distribution. 1411distribution.
1309=head3 Explanation of the columns 1413=head3 Explanation of the columns
1310 1414
1311I<sockets> is the number of sockets, and twice the number of "servers" (as 1415I<sockets> is the number of sockets, and twice the number of "servers" (as
1312each server has a read and write socket end). 1416each server has a read and write socket end).
1313 1417
1314I<create> is the time it takes to create a socketpair (which is 1418I<create> is the time it takes to create a socket pair (which is
1315nontrivial) and two watchers: an I/O watcher and a timeout watcher. 1419nontrivial) and two watchers: an I/O watcher and a timeout watcher.
1316 1420
1317I<request>, the most important value, is the time it takes to handle a 1421I<request>, the most important value, is the time it takes to handle a
1318single "request", that is, reading the token from the pipe and forwarding 1422single "request", that is, reading the token from the pipe and forwarding
1319it to another server. This includes deleting the old timeout and creating 1423it to another server. This includes deleting the old timeout and creating
1392speed most when you have lots of watchers, not when you only have a few of 1496speed most when you have lots of watchers, not when you only have a few of
1393them). 1497them).
1394 1498
1395EV is again fastest. 1499EV is again fastest.
1396 1500
1397Perl again comes second. It is noticably faster than the C-based event 1501Perl again comes second. It is noticeably faster than the C-based event
1398loops Event and Glib, although the difference is too small to really 1502loops Event and Glib, although the difference is too small to really
1399matter. 1503matter.
1400 1504
1401POE also performs much better in this case, but is is still far behind the 1505POE also performs much better in this case, but is is still far behind the
1402others. 1506others.
1442probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1546probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1443 1547
1444 1548
1445=head1 SEE ALSO 1549=head1 SEE ALSO
1446 1550
1551Utility functions: L<AnyEvent::Util>.
1552
1447Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>, 1553Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>,
1448L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 1554L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
1449 1555
1450Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 1556Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
1451L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 1557L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
1452L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 1558L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
1453L<AnyEvent::Impl::POE>. 1559L<AnyEvent::Impl::POE>.
1454 1560
1561Non-blocking file handles, sockets, TCP clients and
1562servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>.
1563
1564Asynchronous DNS: L<AnyEvent::DNS>.
1565
1455Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>, 1566Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>,
1456 1567
1457Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1568Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1458 1569
1459 1570
1460=head1 AUTHOR 1571=head1 AUTHOR
1461 1572
1462 Marc Lehmann <schmorp@schmorp.de> 1573 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines