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.115 by root, Sat May 10 21:47:28 2008 UTC vs.
Revision 1.142 by root, Tue May 27 02:34: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
… …
48isn't itself. What's worse, all the potential users of your module are 48isn't itself. What's worse, all the potential users of your module are
49I<also> forced to use the same event loop you use. 49I<also> forced to use the same event loop you use.
50 50
51AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 51AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
52fine. AnyEvent + Tk works fine etc. etc. but none of these work together 52fine. AnyEvent + Tk works fine etc. etc. but none of these work together
53with the rest: POE + IO::Async? no go. Tk + Event? no go. Again: if 53with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if
54your module uses one of those, every user of your module has to use it, 54your module uses one of those, every user of your module has to use it,
55too. But if your module uses AnyEvent, it works transparently with all 55too. But if your module uses AnyEvent, it works transparently with all
56event models it supports (including stuff like POE and IO::Async, as long 56event models it supports (including stuff like POE and IO::Async, as long
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, AnyEvent comes with a big (and fully optional!) toolbox
68of useful functionality, such as an asynchronous DNS resolver, 100%
69non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms
70such as Windows) and lots of real-world knowledge and workarounds for
71platform bugs and differences.
72
67Of course, if you want lots of policy (this can arguably be somewhat 73Now, if you I<do want> lots of policy (this can arguably be somewhat
68useful) and you want to force your users to use the one and only event 74useful) and you want to force your users to use the one and only event
69model, you should I<not> use this module. 75model, you should I<not> use this module.
70 76
71=head1 DESCRIPTION 77=head1 DESCRIPTION
72 78
… …
102starts using it, all bets are off. Maybe you should tell their authors to 108starts using it, all bets are off. Maybe you should tell their authors to
103use AnyEvent so their modules work together with others seamlessly... 109use AnyEvent so their modules work together with others seamlessly...
104 110
105The pure-perl implementation of AnyEvent is called 111The pure-perl implementation of AnyEvent is called
106C<AnyEvent::Impl::Perl>. Like other event modules you can load it 112C<AnyEvent::Impl::Perl>. Like other event modules you can load it
107explicitly. 113explicitly and enjoy the high availability of that event loop :)
108 114
109=head1 WATCHERS 115=head1 WATCHERS
110 116
111AnyEvent has the central concept of a I<watcher>, which is an object that 117AnyEvent 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 118stores relevant data for each kind of event you are waiting for, such as
113the callback to call, the filehandle to watch, etc. 119the callback to call, the file handle to watch, etc.
114 120
115These watchers are normal Perl objects with normal Perl lifetime. After 121These watchers are normal Perl objects with normal Perl lifetime. After
116creating a watcher it will immediately "watch" for events and invoke the 122creating a watcher it will immediately "watch" for events and invoke the
117callback when the event occurs (of course, only when the event model 123callback when the event occurs (of course, only when the event model
118is in control). 124is in control).
… …
237 243
238Although the callback might get passed parameters, their value and 244Although the callback might get passed parameters, their value and
239presence is undefined and you cannot rely on them. Portable AnyEvent 245presence is undefined and you cannot rely on them. Portable AnyEvent
240callbacks cannot use arguments passed to signal watcher callbacks. 246callbacks cannot use arguments passed to signal watcher callbacks.
241 247
242Multiple signal occurances can be clumped together into one callback 248Multiple signal occurrences can be clumped together into one callback
243invocation, and callback invocation will be synchronous. synchronous means 249invocation, and callback invocation will be synchronous. Synchronous means
244that it might take a while until the signal gets handled by the process, 250that it might take a while until the signal gets handled by the process,
245but it is guarenteed not to interrupt any other callbacks. 251but it is guaranteed not to interrupt any other callbacks.
246 252
247The main advantage of using these watchers is that you can share a signal 253The main advantage of using these watchers is that you can share a signal
248between multiple watchers. 254between multiple watchers.
249 255
250This watcher might use C<%SIG>, so programs overwriting those signals 256This watcher might use C<%SIG>, so programs overwriting those signals
… …
310Condition variables can be created by calling the C<< AnyEvent->condvar 316Condition variables can be created by calling the C<< AnyEvent->condvar
311>> method, usually without arguments. The only argument pair allowed is 317>> method, usually without arguments. The only argument pair allowed is
312C<cb>, which specifies a callback to be called when the condition variable 318C<cb>, which specifies a callback to be called when the condition variable
313becomes true. 319becomes true.
314 320
315After creation, the conditon variable is "false" until it becomes "true" 321After creation, the condition variable is "false" until it becomes "true"
316by calling the C<send> method. 322by calling the C<send> method (or calling the condition variable as if it
323were a callback, read about the caveats in the description for the C<<
324->send >> method).
317 325
318Condition variables are similar to callbacks, except that you can 326Condition variables are similar to callbacks, except that you can
319optionally wait for them. They can also be called merge points - points 327optionally wait for them. They can also be called merge points - points
320in time where multiple outstandign events have been processed. And yet 328in time where multiple outstanding events have been processed. And yet
321another way to call them is transations - each condition variable can be 329another way to call them is transactions - each condition variable can be
322used to represent a transaction, which finishes at some point and delivers 330used to represent a transaction, which finishes at some point and delivers
323a result. 331a result.
324 332
325Condition variables are very useful to signal that something has finished, 333Condition variables are very useful to signal that something has finished,
326for example, if you write a module that does asynchronous http requests, 334for example, if you write a module that does asynchronous http requests,
… …
332you can block your main program until an event occurs - for example, you 340you can block your main program until an event occurs - for example, you
333could C<< ->recv >> in your main program until the user clicks the Quit 341could C<< ->recv >> in your main program until the user clicks the Quit
334button of your app, which would C<< ->send >> the "quit" event. 342button of your app, which would C<< ->send >> the "quit" event.
335 343
336Note that condition variables recurse into the event loop - if you have 344Note that condition variables recurse into the event loop - if you have
337two pieces of code that call C<< ->recv >> in a round-robbin fashion, you 345two pieces of code that call C<< ->recv >> in a round-robin fashion, you
338lose. Therefore, condition variables are good to export to your caller, but 346lose. Therefore, condition variables are good to export to your caller, but
339you should avoid making a blocking wait yourself, at least in callbacks, 347you should avoid making a blocking wait yourself, at least in callbacks,
340as this asks for trouble. 348as this asks for trouble.
341 349
342Condition variables are represented by hash refs in perl, and the keys 350Condition variables are represented by hash refs in perl, and the keys
… …
347 355
348There are two "sides" to a condition variable - the "producer side" which 356There are two "sides" to a condition variable - the "producer side" which
349eventually calls C<< -> send >>, and the "consumer side", which waits 357eventually calls C<< -> send >>, and the "consumer side", which waits
350for the send to occur. 358for the send to occur.
351 359
352Example: 360Example: wait for a timer.
353 361
354 # wait till the result is ready 362 # wait till the result is ready
355 my $result_ready = AnyEvent->condvar; 363 my $result_ready = AnyEvent->condvar;
356 364
357 # do something such as adding a timer 365 # do something such as adding a timer
… …
365 373
366 # this "blocks" (while handling events) till the callback 374 # this "blocks" (while handling events) till the callback
367 # calls send 375 # calls send
368 $result_ready->recv; 376 $result_ready->recv;
369 377
378Example: wait for a timer, but take advantage of the fact that
379condition variables are also code references.
380
381 my $done = AnyEvent->condvar;
382 my $delay = AnyEvent->timer (after => 5, cb => $done);
383 $done->recv;
384
370=head3 METHODS FOR PRODUCERS 385=head3 METHODS FOR PRODUCERS
371 386
372These methods should only be used by the producing side, i.e. the 387These methods should only be used by the producing side, i.e. the
373code/module that eventually sends the signal. Note that it is also 388code/module that eventually sends the signal. Note that it is also
374the producer side which creates the condvar in most cases, but it isn't 389the producer side which creates the condvar in most cases, but it isn't
… …
385If a callback has been set on the condition variable, it is called 400If a callback has been set on the condition variable, it is called
386immediately from within send. 401immediately from within send.
387 402
388Any arguments passed to the C<send> call will be returned by all 403Any arguments passed to the C<send> call will be returned by all
389future C<< ->recv >> calls. 404future C<< ->recv >> calls.
405
406Condition variables are overloaded so one can call them directly
407(as a code reference). Calling them directly is the same as calling
408C<send>. Note, however, that many C-based event loops do not handle
409overloading, so as tempting as it may be, passing a condition variable
410instead of a callback does not work. Both the pure perl and EV loops
411support overloading, however, as well as all functions that use perl to
412invoke a callback (as in L<AnyEvent::Socket> and L<AnyEvent::DNS> for
413example).
390 414
391=item $cv->croak ($error) 415=item $cv->croak ($error)
392 416
393Similar to send, but causes all call's to C<< ->recv >> to invoke 417Similar to send, but causes all call's to C<< ->recv >> to invoke
394C<Carp::croak> with the given error message/object/scalar. 418C<Carp::croak> with the given error message/object/scalar.
… …
443doesn't execute once). 467doesn't execute once).
444 468
445This is the general pattern when you "fan out" into multiple subrequests: 469This 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> 470use 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 471is called at least once, and then, for each subrequest you start, call
448C<begin> and for eahc subrequest you finish, call C<end>. 472C<begin> and for each subrequest you finish, call C<end>.
449 473
450=back 474=back
451 475
452=head3 METHODS FOR CONSUMERS 476=head3 METHODS FOR CONSUMERS
453 477
… …
475(programs might want to do that to stay interactive), so I<if you are 499(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 500using 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 501caller decide whether the call will block or not (for example, by coupling
478condition variables with some kind of request results and supporting 502condition variables with some kind of request results and supporting
479callbacks so the caller knows that getting the result will not block, 503callbacks so the caller knows that getting the result will not block,
480while still suppporting blocking waits if the caller so desires). 504while still supporting blocking waits if the caller so desires).
481 505
482Another reason I<never> to C<< ->recv >> in a module is that you cannot 506Another reason I<never> to C<< ->recv >> in a module is that you cannot
483sensibly have two C<< ->recv >>'s in parallel, as that would require 507sensibly have two C<< ->recv >>'s in parallel, as that would require
484multiple interpreters or coroutines/threads, none of which C<AnyEvent> 508multiple interpreters or coroutines/threads, none of which C<AnyEvent>
485can supply. 509can supply.
… …
601 625
602If it doesn't care, it can just "use AnyEvent" and use it itself, or not 626If it doesn't care, it can just "use AnyEvent" and use it itself, or not
603do anything special (it does not need to be event-based) and let AnyEvent 627do anything special (it does not need to be event-based) and let AnyEvent
604decide which implementation to chose if some module relies on it. 628decide which implementation to chose if some module relies on it.
605 629
606If the main program relies on a specific event model. For example, in 630If the main program relies on a specific event model - for example, in
607Gtk2 programs you have to rely on the Glib module. You should load the 631Gtk2 programs you have to rely on the Glib module - you should load the
608event module before loading AnyEvent or any module that uses it: generally 632event module before loading AnyEvent or any module that uses it: generally
609speaking, you should load it as early as possible. The reason is that 633speaking, you should load it as early as possible. The reason is that
610modules might create watchers when they are loaded, and AnyEvent will 634modules might create watchers when they are loaded, and AnyEvent will
611decide on the event model to use as soon as it creates watchers, and it 635decide on the event model to use as soon as it creates watchers, and it
612might chose the wrong one unless you load the correct one yourself. 636might chose the wrong one unless you load the correct one yourself.
613 637
614You can chose to use a rather inefficient pure-perl implementation by 638You can chose to use a pure-perl implementation by loading the
615loading the C<AnyEvent::Impl::Perl> module, which gives you similar 639C<AnyEvent::Impl::Perl> module, which gives you similar behaviour
616behaviour everywhere, but letting AnyEvent chose is generally better. 640everywhere, but letting AnyEvent chose the model is generally better.
641
642=head2 MAINLOOP EMULATION
643
644Sometimes (often for short test scripts, or even standalone programs who
645only want to use AnyEvent), you do not want to run a specific event loop.
646
647In that case, you can use a condition variable like this:
648
649 AnyEvent->condvar->recv;
650
651This has the effect of entering the event loop and looping forever.
652
653Note that usually your program has some exit condition, in which case
654it is better to use the "traditional" approach of storing a condition
655variable somewhere, waiting for it, and sending it when the program should
656exit cleanly.
657
617 658
618=head1 OTHER MODULES 659=head1 OTHER MODULES
619 660
620The following is a non-exhaustive list of additional modules that use 661The following is a non-exhaustive list of additional modules that use
621AnyEvent and can therefore be mixed easily with other AnyEvent modules 662AnyEvent and can therefore be mixed easily with other AnyEvent modules
… …
631 672
632=item L<AnyEvent::Handle> 673=item L<AnyEvent::Handle>
633 674
634Provide read and write buffers and manages watchers for reads and writes. 675Provide read and write buffers and manages watchers for reads and writes.
635 676
677=item L<AnyEvent::Socket>
678
679Provides various utility functions for (internet protocol) sockets,
680addresses and name resolution. Also functions to create non-blocking tcp
681connections or tcp servers, with IPv6 and SRV record support and more.
682
683=item L<AnyEvent::DNS>
684
685Provides rich asynchronous DNS resolver capabilities.
686
636=item L<AnyEvent::HTTPD> 687=item L<AnyEvent::HTTPD>
637 688
638Provides a simple web application server framework. 689Provides a simple web application server framework.
639
640=item L<AnyEvent::DNS>
641
642Provides asynchronous DNS resolver capabilities, beyond what
643L<AnyEvent::Util> offers.
644 690
645=item L<AnyEvent::FastPing> 691=item L<AnyEvent::FastPing>
646 692
647The fastest ping in the west. 693The fastest ping in the west.
648 694
… …
691no warnings; 737no warnings;
692use strict; 738use strict;
693 739
694use Carp; 740use Carp;
695 741
696our $VERSION = '3.4'; 742our $VERSION = '4.05';
697our $MODEL; 743our $MODEL;
698 744
699our $AUTOLOAD; 745our $AUTOLOAD;
700our @ISA; 746our @ISA;
701 747
748our @REGISTRY;
749
750our $WIN32;
751
752BEGIN {
753 my $win32 = ! ! ($^O =~ /mswin32/i);
754 eval "sub WIN32(){ $win32 }";
755}
756
702our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 757our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
703 758
704our @REGISTRY; 759our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
760
761{
762 my $idx;
763 $PROTOCOL{$_} = ++$idx
764 for reverse split /\s*,\s*/,
765 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
766}
705 767
706my @models = ( 768my @models = (
707 [EV:: => AnyEvent::Impl::EV::], 769 [EV:: => AnyEvent::Impl::EV::],
708 [Event:: => AnyEvent::Impl::Event::], 770 [Event:: => AnyEvent::Impl::Event::],
709 [Tk:: => AnyEvent::Impl::Tk::],
710 [Wx:: => AnyEvent::Impl::POE::],
711 [Prima:: => AnyEvent::Impl::POE::],
712 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 771 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
713 # everything below here will not be autoprobed as the pureperl backend should work everywhere 772 # everything below here will not be autoprobed
714 [Glib:: => AnyEvent::Impl::Glib::], 773 # as the pureperl backend should work everywhere
774 # and is usually faster
775 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
776 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
715 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 777 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
716 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 778 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
717 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 779 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
780 [Wx:: => AnyEvent::Impl::POE::],
781 [Prima:: => AnyEvent::Impl::POE::],
718); 782);
719 783
720our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); 784our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY);
721 785
722our @post_detect; 786our @post_detect;
… …
730 1 794 1
731 } else { 795 } else {
732 push @post_detect, $cb; 796 push @post_detect, $cb;
733 797
734 defined wantarray 798 defined wantarray
735 ? bless \$cb, "AnyEvent::Util::Guard" 799 ? bless \$cb, "AnyEvent::Util::PostDetect"
736 : () 800 : ()
737 } 801 }
738} 802}
739 803
740sub AnyEvent::Util::Guard::DESTROY { 804sub AnyEvent::Util::PostDetect::DESTROY {
741 @post_detect = grep $_ != ${$_[0]}, @post_detect; 805 @post_detect = grep $_ != ${$_[0]}, @post_detect;
742} 806}
743 807
744sub detect() { 808sub detect() {
745 unless ($MODEL) { 809 unless ($MODEL) {
746 no strict 'refs'; 810 no strict 'refs';
811 local $SIG{__DIE__};
747 812
748 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 813 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
749 my $model = "AnyEvent::Impl::$1"; 814 my $model = "AnyEvent::Impl::$1";
750 if (eval "require $model") { 815 if (eval "require $model") {
751 $MODEL = $model; 816 $MODEL = $model;
… …
811package AnyEvent::Base; 876package AnyEvent::Base;
812 877
813# default implementation for ->condvar 878# default implementation for ->condvar
814 879
815sub condvar { 880sub condvar {
816 bless {}, "AnyEvent::Base::CondVar" 881 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
817} 882}
818 883
819# default implementation for ->signal 884# default implementation for ->signal
820 885
821our %SIG_CB; 886our %SIG_CB;
… …
874 or Carp::croak "required option 'pid' is missing"; 939 or Carp::croak "required option 'pid' is missing";
875 940
876 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 941 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
877 942
878 unless ($WNOHANG) { 943 unless ($WNOHANG) {
879 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1; 944 $WNOHANG = eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
880 } 945 }
881 946
882 unless ($CHLD_W) { 947 unless ($CHLD_W) {
883 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 948 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
884 # child could be a zombie already, so make at least one round 949 # child could be a zombie already, so make at least one round
… …
895 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} }; 960 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
896 961
897 undef $CHLD_W unless keys %PID_CB; 962 undef $CHLD_W unless keys %PID_CB;
898} 963}
899 964
900package AnyEvent::Base::CondVar; 965package AnyEvent::CondVar;
901 966
902# wake up the waiter 967our @ISA = AnyEvent::CondVar::Base::;
968
969package AnyEvent::CondVar::Base;
970
971use overload
972 '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
973 fallback => 1;
974
903sub _send { 975sub _send {
904 &{ delete $_[0]{_ae_cb} } if $_[0]{_ae_cb}; 976 # nop
905} 977}
906 978
907sub send { 979sub send {
908 my $cv = shift; 980 my $cv = shift;
909 $cv->{_ae_sent} = [@_]; 981 $cv->{_ae_sent} = [@_];
982 (delete $cv->{_ae_cb})->($cv) if $cv->{_ae_cb};
910 $cv->_send; 983 $cv->_send;
911} 984}
912 985
913sub croak { 986sub croak {
914 $_[0]{_ae_croak} = $_[1]; 987 $_[0]{_ae_croak} = $_[1];
… …
917 990
918sub ready { 991sub ready {
919 $_[0]{_ae_sent} 992 $_[0]{_ae_sent}
920} 993}
921 994
995sub _wait {
996 AnyEvent->one_event while !$_[0]{_ae_sent};
997}
998
922sub recv { 999sub recv {
923 AnyEvent->one_event while !$_[0]{_ae_sent}; 1000 $_[0]->_wait;
924 1001
925 Carp::croak $_[0]{_ae_croak} if $_[0]{_ae_croak}; 1002 Carp::croak $_[0]{_ae_croak} if $_[0]{_ae_croak};
926 wantarray ? @{ $_[0]{_ae_sent} } : $_[0]{_ae_sent}[0] 1003 wantarray ? @{ $_[0]{_ae_sent} } : $_[0]{_ae_sent}[0]
927} 1004}
928 1005
… …
936 $_[0]{_ae_end_cb} = $_[1] if @_ > 1; 1013 $_[0]{_ae_end_cb} = $_[1] if @_ > 1;
937} 1014}
938 1015
939sub end { 1016sub end {
940 return if --$_[0]{_ae_counter}; 1017 return if --$_[0]{_ae_counter};
941 &{ $_[0]{_ae_end_cb} } if $_[0]{_ae_end_cb}; 1018 &{ $_[0]{_ae_end_cb} || sub { $_[0]->send } };
942} 1019}
943 1020
944# undocumented/compatibility with pre-3.4 1021# undocumented/compatibility with pre-3.4
945*broadcast = \&send; 1022*broadcast = \&send;
946*wait = \&recv; 1023*wait = \&_wait;
947 1024
948=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1025=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
949 1026
950This is an advanced topic that you do not normally need to use AnyEvent in 1027This is an advanced topic that you do not normally need to use AnyEvent in
951a module. This section is only of use to event loop authors who want to 1028a module. This section is only of use to event loop authors who want to
… …
1008model it chooses. 1085model it chooses.
1009 1086
1010=item C<PERL_ANYEVENT_MODEL> 1087=item C<PERL_ANYEVENT_MODEL>
1011 1088
1012This can be used to specify the event model to be used by AnyEvent, before 1089This can be used to specify the event model to be used by AnyEvent, before
1013autodetection and -probing kicks in. It must be a string consisting 1090auto detection and -probing kicks in. It must be a string consisting
1014entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended 1091entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
1015and the resulting module name is loaded and if the load was successful, 1092and the resulting module name is loaded and if the load was successful,
1016used as event model. If it fails to load AnyEvent will proceed with 1093used as event model. If it fails to load AnyEvent will proceed with
1017autodetection and -probing. 1094auto detection and -probing.
1018 1095
1019This functionality might change in future versions. 1096This functionality might change in future versions.
1020 1097
1021For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you 1098For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1022could start your program like this: 1099could start your program like this:
1023 1100
1024 PERL_ANYEVENT_MODEL=Perl perl ... 1101 PERL_ANYEVENT_MODEL=Perl perl ...
1102
1103=item C<PERL_ANYEVENT_PROTOCOLS>
1104
1105Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1106for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1107of auto probing).
1108
1109Must be set to a comma-separated list of protocols or address families,
1110current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1111used, and preference will be given to protocols mentioned earlier in the
1112list.
1113
1114This variable can effectively be used for denial-of-service attacks
1115against local programs (e.g. when setuid), although the impact is likely
1116small, as the program has to handle connection errors already-
1117
1118Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1119but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1120- only support IPv4, never try to resolve or contact IPv6
1121addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1122IPv6, but prefer IPv6 over IPv4.
1123
1124=item C<PERL_ANYEVENT_EDNS0>
1125
1126Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
1127for DNS. This extension is generally useful to reduce DNS traffic, but
1128some (broken) firewalls drop such DNS packets, which is why it is off by
1129default.
1130
1131Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1132EDNS0 in its DNS requests.
1133
1134=item C<PERL_ANYEVENT_MAX_FORKS>
1135
1136The maximum number of child processes that C<AnyEvent::Util::fork_call>
1137will create in parallel.
1025 1138
1026=back 1139=back
1027 1140
1028=head1 EXAMPLE PROGRAM 1141=head1 EXAMPLE PROGRAM
1029 1142
… …
1040 poll => 'r', 1153 poll => 'r',
1041 cb => sub { 1154 cb => sub {
1042 warn "io event <$_[0]>\n"; # will always output <r> 1155 warn "io event <$_[0]>\n"; # will always output <r>
1043 chomp (my $input = <STDIN>); # read a line 1156 chomp (my $input = <STDIN>); # read a line
1044 warn "read: $input\n"; # output what has been read 1157 warn "read: $input\n"; # output what has been read
1045 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 1158 $cv->send if $input =~ /^q/i; # quit program if /^q/i
1046 }, 1159 },
1047 ); 1160 );
1048 1161
1049 my $time_watcher; # can only be used once 1162 my $time_watcher; # can only be used once
1050 1163
… …
1055 }); 1168 });
1056 } 1169 }
1057 1170
1058 new_timer; # create first timer 1171 new_timer; # create first timer
1059 1172
1060 $cv->wait; # wait until user enters /^q/i 1173 $cv->recv; # wait until user enters /^q/i
1061 1174
1062=head1 REAL-WORLD EXAMPLE 1175=head1 REAL-WORLD EXAMPLE
1063 1176
1064Consider the L<Net::FCP> module. It features (among others) the following 1177Consider the L<Net::FCP> module. It features (among others) the following
1065API calls, which are to freenet what HTTP GET requests are to http: 1178API calls, which are to freenet what HTTP GET requests are to http:
… …
1115 syswrite $txn->{fh}, $txn->{request} 1228 syswrite $txn->{fh}, $txn->{request}
1116 or die "connection or write error"; 1229 or die "connection or write error";
1117 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r }); 1230 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r });
1118 1231
1119Again, C<fh_ready_r> waits till all data has arrived, and then stores the 1232Again, C<fh_ready_r> waits till all data has arrived, and then stores the
1120result and signals any possible waiters that the request ahs finished: 1233result and signals any possible waiters that the request has finished:
1121 1234
1122 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 1235 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
1123 1236
1124 if (end-of-file or data complete) { 1237 if (end-of-file or data complete) {
1125 $txn->{result} = $txn->{buf}; 1238 $txn->{result} = $txn->{buf};
1126 $txn->{finished}->broadcast; 1239 $txn->{finished}->send;
1127 $txb->{cb}->($txn) of $txn->{cb}; # also call callback 1240 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
1128 } 1241 }
1129 1242
1130The C<result> method, finally, just waits for the finished signal (if the 1243The C<result> method, finally, just waits for the finished signal (if the
1131request was already finished, it doesn't wait, of course, and returns the 1244request was already finished, it doesn't wait, of course, and returns the
1132data: 1245data:
1133 1246
1134 $txn->{finished}->wait; 1247 $txn->{finished}->recv;
1135 return $txn->{result}; 1248 return $txn->{result};
1136 1249
1137The actual code goes further and collects all errors (C<die>s, exceptions) 1250The actual code goes further and collects all errors (C<die>s, exceptions)
1138that occured during request processing. The C<result> method detects 1251that occurred during request processing. The C<result> method detects
1139whether an exception as thrown (it is stored inside the $txn object) 1252whether an exception as thrown (it is stored inside the $txn object)
1140and just throws the exception, which means connection errors and other 1253and just throws the exception, which means connection errors and other
1141problems get reported tot he code that tries to use the result, not in a 1254problems get reported tot he code that tries to use the result, not in a
1142random callback. 1255random callback.
1143 1256
… …
1174 1287
1175 my $quit = AnyEvent->condvar; 1288 my $quit = AnyEvent->condvar;
1176 1289
1177 $fcp->txn_client_get ($url)->cb (sub { 1290 $fcp->txn_client_get ($url)->cb (sub {
1178 ... 1291 ...
1179 $quit->broadcast; 1292 $quit->send;
1180 }); 1293 });
1181 1294
1182 $quit->wait; 1295 $quit->recv;
1183 1296
1184 1297
1185=head1 BENCHMARKS 1298=head1 BENCHMARKS
1186 1299
1187To give you an idea of the performance and overheads that AnyEvent adds 1300To give you an idea of the performance and overheads that AnyEvent adds
… …
1189of various event loops I prepared some benchmarks. 1302of various event loops I prepared some benchmarks.
1190 1303
1191=head2 BENCHMARKING ANYEVENT OVERHEAD 1304=head2 BENCHMARKING ANYEVENT OVERHEAD
1192 1305
1193Here is a benchmark of various supported event models used natively and 1306Here is a benchmark of various supported event models used natively and
1194through anyevent. The benchmark creates a lot of timers (with a zero 1307through AnyEvent. The benchmark creates a lot of timers (with a zero
1195timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 1308timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
1196which it is), lets them fire exactly once and destroys them again. 1309which it is), lets them fire exactly once and destroys them again.
1197 1310
1198Source code for this benchmark is found as F<eg/bench> in the AnyEvent 1311Source code for this benchmark is found as F<eg/bench> in the AnyEvent
1199distribution. 1312distribution.
… …
1216all watchers, to avoid adding memory overhead. That means closure creation 1329all watchers, to avoid adding memory overhead. That means closure creation
1217and memory usage is not included in the figures. 1330and memory usage is not included in the figures.
1218 1331
1219I<invoke> is the time, in microseconds, used to invoke a simple 1332I<invoke> is the time, in microseconds, used to invoke a simple
1220callback. The callback simply counts down a Perl variable and after it was 1333callback. The callback simply counts down a Perl variable and after it was
1221invoked "watcher" times, it would C<< ->broadcast >> a condvar once to 1334invoked "watcher" times, it would C<< ->send >> a condvar once to
1222signal the end of this phase. 1335signal the end of this phase.
1223 1336
1224I<destroy> is the time, in microseconds, that it takes to destroy a single 1337I<destroy> is the time, in microseconds, that it takes to destroy a single
1225watcher. 1338watcher.
1226 1339
… …
1322 1435
1323=back 1436=back
1324 1437
1325=head2 BENCHMARKING THE LARGE SERVER CASE 1438=head2 BENCHMARKING THE LARGE SERVER CASE
1326 1439
1327This benchmark atcually benchmarks the event loop itself. It works by 1440This benchmark actually benchmarks the event loop itself. It works by
1328creating a number of "servers": each server consists of a socketpair, a 1441creating a number of "servers": each server consists of a socket pair, a
1329timeout watcher that gets reset on activity (but never fires), and an I/O 1442timeout watcher that gets reset on activity (but never fires), and an I/O
1330watcher waiting for input on one side of the socket. Each time the socket 1443watcher waiting for input on one side of the socket. Each time the socket
1331watcher reads a byte it will write that byte to a random other "server". 1444watcher reads a byte it will write that byte to a random other "server".
1332 1445
1333The effect is that there will be a lot of I/O watchers, only part of which 1446The effect is that there will be a lot of I/O watchers, only part of which
1334are active at any one point (so there is a constant number of active 1447are active at any one point (so there is a constant number of active
1335fds for each loop iterstaion, but which fds these are is random). The 1448fds for each loop iteration, but which fds these are is random). The
1336timeout is reset each time something is read because that reflects how 1449timeout is reset each time something is read because that reflects how
1337most timeouts work (and puts extra pressure on the event loops). 1450most timeouts work (and puts extra pressure on the event loops).
1338 1451
1339In this benchmark, we use 10000 socketpairs (20000 sockets), of which 100 1452In this benchmark, we use 10000 socket pairs (20000 sockets), of which 100
1340(1%) are active. This mirrors the activity of large servers with many 1453(1%) are active. This mirrors the activity of large servers with many
1341connections, most of which are idle at any one point in time. 1454connections, most of which are idle at any one point in time.
1342 1455
1343Source code for this benchmark is found as F<eg/bench2> in the AnyEvent 1456Source code for this benchmark is found as F<eg/bench2> in the AnyEvent
1344distribution. 1457distribution.
… …
1346=head3 Explanation of the columns 1459=head3 Explanation of the columns
1347 1460
1348I<sockets> is the number of sockets, and twice the number of "servers" (as 1461I<sockets> is the number of sockets, and twice the number of "servers" (as
1349each server has a read and write socket end). 1462each server has a read and write socket end).
1350 1463
1351I<create> is the time it takes to create a socketpair (which is 1464I<create> is the time it takes to create a socket pair (which is
1352nontrivial) and two watchers: an I/O watcher and a timeout watcher. 1465nontrivial) and two watchers: an I/O watcher and a timeout watcher.
1353 1466
1354I<request>, the most important value, is the time it takes to handle a 1467I<request>, the most important value, is the time it takes to handle a
1355single "request", that is, reading the token from the pipe and forwarding 1468single "request", that is, reading the token from the pipe and forwarding
1356it to another server. This includes deleting the old timeout and creating 1469it to another server. This includes deleting the old timeout and creating
… …
1429speed most when you have lots of watchers, not when you only have a few of 1542speed most when you have lots of watchers, not when you only have a few of
1430them). 1543them).
1431 1544
1432EV is again fastest. 1545EV is again fastest.
1433 1546
1434Perl again comes second. It is noticably faster than the C-based event 1547Perl again comes second. It is noticeably faster than the C-based event
1435loops Event and Glib, although the difference is too small to really 1548loops Event and Glib, although the difference is too small to really
1436matter. 1549matter.
1437 1550
1438POE also performs much better in this case, but is is still far behind the 1551POE also performs much better in this case, but is is still far behind the
1439others. 1552others.
… …
1479probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1592probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1480 1593
1481 1594
1482=head1 SEE ALSO 1595=head1 SEE ALSO
1483 1596
1597Utility functions: L<AnyEvent::Util>.
1598
1484Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>, 1599Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>,
1485L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 1600L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
1486 1601
1487Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 1602Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
1488L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 1603L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
1489L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 1604L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
1490L<AnyEvent::Impl::POE>. 1605L<AnyEvent::Impl::POE>.
1491 1606
1607Non-blocking file handles, sockets, TCP clients and
1608servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>.
1609
1610Asynchronous DNS: L<AnyEvent::DNS>.
1611
1492Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>, 1612Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>,
1493 1613
1494Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1614Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1495 1615
1496 1616
1497=head1 AUTHOR 1617=head1 AUTHOR
1498 1618
1499 Marc Lehmann <schmorp@schmorp.de> 1619 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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