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.116 by root, Sat May 10 22:30:28 2008 UTC vs.
Revision 1.140 by root, Mon May 26 06:18:53 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
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
310Condition variables can be created by calling the C<< AnyEvent->condvar 310Condition variables can be created by calling the C<< AnyEvent->condvar
311>> method, usually without arguments. The only argument pair allowed is 311>> method, usually without arguments. The only argument pair allowed is
312C<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
313becomes true. 313becomes true.
314 314
315After creation, the conditon variable is "false" until it becomes "true" 315After creation, the condition variable is "false" until it becomes "true"
316by calling the C<send> method. 316by calling the C<send> method (or calling the condition variable as if it
317were a callback, read about the caveats in the description for the C<<
318->send >> method).
317 319
318Condition variables are similar to callbacks, except that you can 320Condition variables are similar to callbacks, except that you can
319optionally wait for them. They can also be called merge points - points 321optionally wait for them. They can also be called merge points - points
320in time where multiple outstandign events have been processed. And yet 322in time where multiple outstanding events have been processed. And yet
321another way to call them is transations - each condition variable can be 323another way to call them is transactions - each condition variable can be
322used to represent a transaction, which finishes at some point and delivers 324used to represent a transaction, which finishes at some point and delivers
323a result. 325a result.
324 326
325Condition variables are very useful to signal that something has finished, 327Condition variables are very useful to signal that something has finished,
326for example, if you write a module that does asynchronous http requests, 328for example, if you write a module that does asynchronous http requests,
332you can block your main program until an event occurs - for example, you 334you 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 335could C<< ->recv >> in your main program until the user clicks the Quit
334button of your app, which would C<< ->send >> the "quit" event. 336button of your app, which would C<< ->send >> the "quit" event.
335 337
336Note that condition variables recurse into the event loop - if you have 338Note 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 339two 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 340lose. Therefore, condition variables are good to export to your caller, but
339you should avoid making a blocking wait yourself, at least in callbacks, 341you should avoid making a blocking wait yourself, at least in callbacks,
340as this asks for trouble. 342as this asks for trouble.
341 343
342Condition variables are represented by hash refs in perl, and the keys 344Condition variables are represented by hash refs in perl, and the keys
347 349
348There are two "sides" to a condition variable - the "producer side" which 350There are two "sides" to a condition variable - the "producer side" which
349eventually calls C<< -> send >>, and the "consumer side", which waits 351eventually calls C<< -> send >>, and the "consumer side", which waits
350for the send to occur. 352for the send to occur.
351 353
352Example: 354Example: wait for a timer.
353 355
354 # wait till the result is ready 356 # wait till the result is ready
355 my $result_ready = AnyEvent->condvar; 357 my $result_ready = AnyEvent->condvar;
356 358
357 # do something such as adding a timer 359 # do something such as adding a timer
365 367
366 # this "blocks" (while handling events) till the callback 368 # this "blocks" (while handling events) till the callback
367 # calls send 369 # calls send
368 $result_ready->recv; 370 $result_ready->recv;
369 371
372Example: wait for a timer, but take advantage of the fact that
373condition variables are also code references.
374
375 my $done = AnyEvent->condvar;
376 my $delay = AnyEvent->timer (after => 5, cb => $done);
377 $done->recv;
378
370=head3 METHODS FOR PRODUCERS 379=head3 METHODS FOR PRODUCERS
371 380
372These methods should only be used by the producing side, i.e. the 381These methods should only be used by the producing side, i.e. the
373code/module that eventually sends the signal. Note that it is also 382code/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 383the 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 394If a callback has been set on the condition variable, it is called
386immediately from within send. 395immediately from within send.
387 396
388Any arguments passed to the C<send> call will be returned by all 397Any arguments passed to the C<send> call will be returned by all
389future C<< ->recv >> calls. 398future C<< ->recv >> calls.
399
400Condition variables are overloaded so one can call them directly
401(as a code reference). Calling them directly is the same as calling
402C<send>. Note, however, that many C-based event loops do not handle
403overloading, so as tempting as it may be, passing a condition variable
404instead of a callback does not work. Both the pure perl and EV loops
405support overloading, however, as well as all functions that use perl to
406invoke a callback (as in L<AnyEvent::Socket> and L<AnyEvent::DNS> for
407example).
390 408
391=item $cv->croak ($error) 409=item $cv->croak ($error)
392 410
393Similar to send, but causes all call's to C<< ->recv >> to invoke 411Similar to send, but causes all call's to C<< ->recv >> to invoke
394C<Carp::croak> with the given error message/object/scalar. 412C<Carp::croak> with the given error message/object/scalar.
443doesn't execute once). 461doesn't execute once).
444 462
445This is the general pattern when you "fan out" into multiple subrequests: 463This 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> 464use 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 465is called at least once, and then, for each subrequest you start, call
448C<begin> and for eahc subrequest you finish, call C<end>. 466C<begin> and for each subrequest you finish, call C<end>.
449 467
450=back 468=back
451 469
452=head3 METHODS FOR CONSUMERS 470=head3 METHODS FOR CONSUMERS
453 471
475(programs might want to do that to stay interactive), so I<if you are 493(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 494using 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 495caller decide whether the call will block or not (for example, by coupling
478condition variables with some kind of request results and supporting 496condition variables with some kind of request results and supporting
479callbacks so the caller knows that getting the result will not block, 497callbacks so the caller knows that getting the result will not block,
480while still suppporting blocking waits if the caller so desires). 498while still supporting blocking waits if the caller so desires).
481 499
482Another reason I<never> to C<< ->recv >> in a module is that you cannot 500Another 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 501sensibly have two C<< ->recv >>'s in parallel, as that would require
484multiple interpreters or coroutines/threads, none of which C<AnyEvent> 502multiple interpreters or coroutines/threads, none of which C<AnyEvent>
485can supply. 503can supply.
601 619
602If it doesn't care, it can just "use AnyEvent" and use it itself, or not 620If 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 621do anything special (it does not need to be event-based) and let AnyEvent
604decide which implementation to chose if some module relies on it. 622decide which implementation to chose if some module relies on it.
605 623
606If the main program relies on a specific event model. For example, in 624If 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 625Gtk2 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 626event module before loading AnyEvent or any module that uses it: generally
609speaking, you should load it as early as possible. The reason is that 627speaking, you should load it as early as possible. The reason is that
610modules might create watchers when they are loaded, and AnyEvent will 628modules 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 629decide 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. 630might chose the wrong one unless you load the correct one yourself.
613 631
614You can chose to use a rather inefficient pure-perl implementation by 632You can chose to use a pure-perl implementation by loading the
615loading the C<AnyEvent::Impl::Perl> module, which gives you similar 633C<AnyEvent::Impl::Perl> module, which gives you similar behaviour
616behaviour everywhere, but letting AnyEvent chose is generally better. 634everywhere, but letting AnyEvent chose the model is generally better.
635
636=head2 MAINLOOP EMULATION
637
638Sometimes (often for short test scripts, or even standalone programs who
639only want to use AnyEvent), you do not want to run a specific event loop.
640
641In that case, you can use a condition variable like this:
642
643 AnyEvent->condvar->recv;
644
645This has the effect of entering the event loop and looping forever.
646
647Note that usually your program has some exit condition, in which case
648it is better to use the "traditional" approach of storing a condition
649variable somewhere, waiting for it, and sending it when the program should
650exit cleanly.
651
617 652
618=head1 OTHER MODULES 653=head1 OTHER MODULES
619 654
620The following is a non-exhaustive list of additional modules that use 655The following is a non-exhaustive list of additional modules that use
621AnyEvent and can therefore be mixed easily with other AnyEvent modules 656AnyEvent and can therefore be mixed easily with other AnyEvent modules
631 666
632=item L<AnyEvent::Handle> 667=item L<AnyEvent::Handle>
633 668
634Provide read and write buffers and manages watchers for reads and writes. 669Provide read and write buffers and manages watchers for reads and writes.
635 670
671=item L<AnyEvent::Socket>
672
673Provides various utility functions for (internet protocol) sockets,
674addresses and name resolution. Also functions to create non-blocking tcp
675connections or tcp servers, with IPv6 and SRV record support and more.
676
677=item L<AnyEvent::DNS>
678
679Provides rich asynchronous DNS resolver capabilities.
680
636=item L<AnyEvent::HTTPD> 681=item L<AnyEvent::HTTPD>
637 682
638Provides a simple web application server framework. 683Provides 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 684
645=item L<AnyEvent::FastPing> 685=item L<AnyEvent::FastPing>
646 686
647The fastest ping in the west. 687The fastest ping in the west.
648 688
691no warnings; 731no warnings;
692use strict; 732use strict;
693 733
694use Carp; 734use Carp;
695 735
696our $VERSION = '3.4'; 736our $VERSION = '4.04';
697our $MODEL; 737our $MODEL;
698 738
699our $AUTOLOAD; 739our $AUTOLOAD;
700our @ISA; 740our @ISA;
701 741
742our @REGISTRY;
743
744our $WIN32;
745
746BEGIN {
747 my $win32 = ! ! ($^O =~ /mswin32/i);
748 eval "sub WIN32(){ $win32 }";
749}
750
702our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 751our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
703 752
704our @REGISTRY; 753our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
754
755{
756 my $idx;
757 $PROTOCOL{$_} = ++$idx
758 for reverse split /\s*,\s*/,
759 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
760}
705 761
706my @models = ( 762my @models = (
707 [EV:: => AnyEvent::Impl::EV::], 763 [EV:: => AnyEvent::Impl::EV::],
708 [Event:: => AnyEvent::Impl::Event::], 764 [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::], 765 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
713 # everything below here will not be autoprobed as the pureperl backend should work everywhere 766 # everything below here will not be autoprobed
714 [Glib:: => AnyEvent::Impl::Glib::], 767 # as the pureperl backend should work everywhere
768 # and is usually faster
769 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
770 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
715 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 771 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
716 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 772 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
717 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 773 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
774 [Wx:: => AnyEvent::Impl::POE::],
775 [Prima:: => AnyEvent::Impl::POE::],
718); 776);
719 777
720our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); 778our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY);
721 779
722our @post_detect; 780our @post_detect;
730 1 788 1
731 } else { 789 } else {
732 push @post_detect, $cb; 790 push @post_detect, $cb;
733 791
734 defined wantarray 792 defined wantarray
735 ? bless \$cb, "AnyEvent::Util::Guard" 793 ? bless \$cb, "AnyEvent::Util::PostDetect"
736 : () 794 : ()
737 } 795 }
738} 796}
739 797
740sub AnyEvent::Util::Guard::DESTROY { 798sub AnyEvent::Util::PostDetect::DESTROY {
741 @post_detect = grep $_ != ${$_[0]}, @post_detect; 799 @post_detect = grep $_ != ${$_[0]}, @post_detect;
742} 800}
743 801
744sub detect() { 802sub detect() {
745 unless ($MODEL) { 803 unless ($MODEL) {
746 no strict 'refs'; 804 no strict 'refs';
805 local $SIG{__DIE__};
747 806
748 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 807 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
749 my $model = "AnyEvent::Impl::$1"; 808 my $model = "AnyEvent::Impl::$1";
750 if (eval "require $model") { 809 if (eval "require $model") {
751 $MODEL = $model; 810 $MODEL = $model;
811package AnyEvent::Base; 870package AnyEvent::Base;
812 871
813# default implementation for ->condvar 872# default implementation for ->condvar
814 873
815sub condvar { 874sub condvar {
816 bless {}, AnyEvent::CondVar:: 875 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
817} 876}
818 877
819# default implementation for ->signal 878# default implementation for ->signal
820 879
821our %SIG_CB; 880our %SIG_CB;
874 or Carp::croak "required option 'pid' is missing"; 933 or Carp::croak "required option 'pid' is missing";
875 934
876 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 935 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
877 936
878 unless ($WNOHANG) { 937 unless ($WNOHANG) {
879 $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1; 938 $WNOHANG = eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
880 } 939 }
881 940
882 unless ($CHLD_W) { 941 unless ($CHLD_W) {
883 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 942 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
884 # child could be a zombie already, so make at least one round 943 # child could be a zombie already, so make at least one round
901 960
902our @ISA = AnyEvent::CondVar::Base::; 961our @ISA = AnyEvent::CondVar::Base::;
903 962
904package AnyEvent::CondVar::Base; 963package AnyEvent::CondVar::Base;
905 964
965use overload
966 '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
967 fallback => 1;
968
906sub _send { 969sub _send {
907 # nop 970 # nop
908} 971}
909 972
910sub send { 973sub send {
944 $_[0]{_ae_end_cb} = $_[1] if @_ > 1; 1007 $_[0]{_ae_end_cb} = $_[1] if @_ > 1;
945} 1008}
946 1009
947sub end { 1010sub end {
948 return if --$_[0]{_ae_counter}; 1011 return if --$_[0]{_ae_counter};
949 &{ $_[0]{_ae_end_cb} } if $_[0]{_ae_end_cb}; 1012 &{ $_[0]{_ae_end_cb} || sub { $_[0]->send } };
950} 1013}
951 1014
952# undocumented/compatibility with pre-3.4 1015# undocumented/compatibility with pre-3.4
953*broadcast = \&send; 1016*broadcast = \&send;
954*wait = \&_wait; 1017*wait = \&_wait;
1016model it chooses. 1079model it chooses.
1017 1080
1018=item C<PERL_ANYEVENT_MODEL> 1081=item C<PERL_ANYEVENT_MODEL>
1019 1082
1020This can be used to specify the event model to be used by AnyEvent, before 1083This can be used to specify the event model to be used by AnyEvent, before
1021autodetection and -probing kicks in. It must be a string consisting 1084auto detection and -probing kicks in. It must be a string consisting
1022entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended 1085entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
1023and the resulting module name is loaded and if the load was successful, 1086and the resulting module name is loaded and if the load was successful,
1024used as event model. If it fails to load AnyEvent will proceed with 1087used as event model. If it fails to load AnyEvent will proceed with
1025autodetection and -probing. 1088auto detection and -probing.
1026 1089
1027This functionality might change in future versions. 1090This functionality might change in future versions.
1028 1091
1029For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you 1092For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1030could start your program like this: 1093could start your program like this:
1031 1094
1032 PERL_ANYEVENT_MODEL=Perl perl ... 1095 PERL_ANYEVENT_MODEL=Perl perl ...
1096
1097=item C<PERL_ANYEVENT_PROTOCOLS>
1098
1099Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1100for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1101of auto probing).
1102
1103Must be set to a comma-separated list of protocols or address families,
1104current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1105used, and preference will be given to protocols mentioned earlier in the
1106list.
1107
1108This variable can effectively be used for denial-of-service attacks
1109against local programs (e.g. when setuid), although the impact is likely
1110small, as the program has to handle connection errors already-
1111
1112Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1113but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1114- only support IPv4, never try to resolve or contact IPv6
1115addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1116IPv6, but prefer IPv6 over IPv4.
1117
1118=item C<PERL_ANYEVENT_EDNS0>
1119
1120Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
1121for DNS. This extension is generally useful to reduce DNS traffic, but
1122some (broken) firewalls drop such DNS packets, which is why it is off by
1123default.
1124
1125Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1126EDNS0 in its DNS requests.
1033 1127
1034=back 1128=back
1035 1129
1036=head1 EXAMPLE PROGRAM 1130=head1 EXAMPLE PROGRAM
1037 1131
1048 poll => 'r', 1142 poll => 'r',
1049 cb => sub { 1143 cb => sub {
1050 warn "io event <$_[0]>\n"; # will always output <r> 1144 warn "io event <$_[0]>\n"; # will always output <r>
1051 chomp (my $input = <STDIN>); # read a line 1145 chomp (my $input = <STDIN>); # read a line
1052 warn "read: $input\n"; # output what has been read 1146 warn "read: $input\n"; # output what has been read
1053 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 1147 $cv->send if $input =~ /^q/i; # quit program if /^q/i
1054 }, 1148 },
1055 ); 1149 );
1056 1150
1057 my $time_watcher; # can only be used once 1151 my $time_watcher; # can only be used once
1058 1152
1063 }); 1157 });
1064 } 1158 }
1065 1159
1066 new_timer; # create first timer 1160 new_timer; # create first timer
1067 1161
1068 $cv->wait; # wait until user enters /^q/i 1162 $cv->recv; # wait until user enters /^q/i
1069 1163
1070=head1 REAL-WORLD EXAMPLE 1164=head1 REAL-WORLD EXAMPLE
1071 1165
1072Consider the L<Net::FCP> module. It features (among others) the following 1166Consider the L<Net::FCP> module. It features (among others) the following
1073API calls, which are to freenet what HTTP GET requests are to http: 1167API calls, which are to freenet what HTTP GET requests are to http:
1123 syswrite $txn->{fh}, $txn->{request} 1217 syswrite $txn->{fh}, $txn->{request}
1124 or die "connection or write error"; 1218 or die "connection or write error";
1125 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r }); 1219 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r });
1126 1220
1127Again, C<fh_ready_r> waits till all data has arrived, and then stores the 1221Again, C<fh_ready_r> waits till all data has arrived, and then stores the
1128result and signals any possible waiters that the request ahs finished: 1222result and signals any possible waiters that the request has finished:
1129 1223
1130 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 1224 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
1131 1225
1132 if (end-of-file or data complete) { 1226 if (end-of-file or data complete) {
1133 $txn->{result} = $txn->{buf}; 1227 $txn->{result} = $txn->{buf};
1134 $txn->{finished}->broadcast; 1228 $txn->{finished}->send;
1135 $txb->{cb}->($txn) of $txn->{cb}; # also call callback 1229 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
1136 } 1230 }
1137 1231
1138The C<result> method, finally, just waits for the finished signal (if the 1232The C<result> method, finally, just waits for the finished signal (if the
1139request was already finished, it doesn't wait, of course, and returns the 1233request was already finished, it doesn't wait, of course, and returns the
1140data: 1234data:
1141 1235
1142 $txn->{finished}->wait; 1236 $txn->{finished}->recv;
1143 return $txn->{result}; 1237 return $txn->{result};
1144 1238
1145The actual code goes further and collects all errors (C<die>s, exceptions) 1239The actual code goes further and collects all errors (C<die>s, exceptions)
1146that occured during request processing. The C<result> method detects 1240that occurred during request processing. The C<result> method detects
1147whether an exception as thrown (it is stored inside the $txn object) 1241whether an exception as thrown (it is stored inside the $txn object)
1148and just throws the exception, which means connection errors and other 1242and just throws the exception, which means connection errors and other
1149problems get reported tot he code that tries to use the result, not in a 1243problems get reported tot he code that tries to use the result, not in a
1150random callback. 1244random callback.
1151 1245
1182 1276
1183 my $quit = AnyEvent->condvar; 1277 my $quit = AnyEvent->condvar;
1184 1278
1185 $fcp->txn_client_get ($url)->cb (sub { 1279 $fcp->txn_client_get ($url)->cb (sub {
1186 ... 1280 ...
1187 $quit->broadcast; 1281 $quit->send;
1188 }); 1282 });
1189 1283
1190 $quit->wait; 1284 $quit->recv;
1191 1285
1192 1286
1193=head1 BENCHMARKS 1287=head1 BENCHMARKS
1194 1288
1195To give you an idea of the performance and overheads that AnyEvent adds 1289To give you an idea of the performance and overheads that AnyEvent adds
1197of various event loops I prepared some benchmarks. 1291of various event loops I prepared some benchmarks.
1198 1292
1199=head2 BENCHMARKING ANYEVENT OVERHEAD 1293=head2 BENCHMARKING ANYEVENT OVERHEAD
1200 1294
1201Here is a benchmark of various supported event models used natively and 1295Here is a benchmark of various supported event models used natively and
1202through anyevent. The benchmark creates a lot of timers (with a zero 1296through AnyEvent. The benchmark creates a lot of timers (with a zero
1203timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 1297timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
1204which it is), lets them fire exactly once and destroys them again. 1298which it is), lets them fire exactly once and destroys them again.
1205 1299
1206Source code for this benchmark is found as F<eg/bench> in the AnyEvent 1300Source code for this benchmark is found as F<eg/bench> in the AnyEvent
1207distribution. 1301distribution.
1224all watchers, to avoid adding memory overhead. That means closure creation 1318all watchers, to avoid adding memory overhead. That means closure creation
1225and memory usage is not included in the figures. 1319and memory usage is not included in the figures.
1226 1320
1227I<invoke> is the time, in microseconds, used to invoke a simple 1321I<invoke> is the time, in microseconds, used to invoke a simple
1228callback. The callback simply counts down a Perl variable and after it was 1322callback. The callback simply counts down a Perl variable and after it was
1229invoked "watcher" times, it would C<< ->broadcast >> a condvar once to 1323invoked "watcher" times, it would C<< ->send >> a condvar once to
1230signal the end of this phase. 1324signal the end of this phase.
1231 1325
1232I<destroy> is the time, in microseconds, that it takes to destroy a single 1326I<destroy> is the time, in microseconds, that it takes to destroy a single
1233watcher. 1327watcher.
1234 1328
1330 1424
1331=back 1425=back
1332 1426
1333=head2 BENCHMARKING THE LARGE SERVER CASE 1427=head2 BENCHMARKING THE LARGE SERVER CASE
1334 1428
1335This benchmark atcually benchmarks the event loop itself. It works by 1429This benchmark actually benchmarks the event loop itself. It works by
1336creating a number of "servers": each server consists of a socketpair, a 1430creating a number of "servers": each server consists of a socket pair, a
1337timeout watcher that gets reset on activity (but never fires), and an I/O 1431timeout watcher that gets reset on activity (but never fires), and an I/O
1338watcher waiting for input on one side of the socket. Each time the socket 1432watcher waiting for input on one side of the socket. Each time the socket
1339watcher reads a byte it will write that byte to a random other "server". 1433watcher reads a byte it will write that byte to a random other "server".
1340 1434
1341The effect is that there will be a lot of I/O watchers, only part of which 1435The effect is that there will be a lot of I/O watchers, only part of which
1342are active at any one point (so there is a constant number of active 1436are active at any one point (so there is a constant number of active
1343fds for each loop iterstaion, but which fds these are is random). The 1437fds for each loop iteration, but which fds these are is random). The
1344timeout is reset each time something is read because that reflects how 1438timeout is reset each time something is read because that reflects how
1345most timeouts work (and puts extra pressure on the event loops). 1439most timeouts work (and puts extra pressure on the event loops).
1346 1440
1347In this benchmark, we use 10000 socketpairs (20000 sockets), of which 100 1441In this benchmark, we use 10000 socket pairs (20000 sockets), of which 100
1348(1%) are active. This mirrors the activity of large servers with many 1442(1%) are active. This mirrors the activity of large servers with many
1349connections, most of which are idle at any one point in time. 1443connections, most of which are idle at any one point in time.
1350 1444
1351Source code for this benchmark is found as F<eg/bench2> in the AnyEvent 1445Source code for this benchmark is found as F<eg/bench2> in the AnyEvent
1352distribution. 1446distribution.
1354=head3 Explanation of the columns 1448=head3 Explanation of the columns
1355 1449
1356I<sockets> is the number of sockets, and twice the number of "servers" (as 1450I<sockets> is the number of sockets, and twice the number of "servers" (as
1357each server has a read and write socket end). 1451each server has a read and write socket end).
1358 1452
1359I<create> is the time it takes to create a socketpair (which is 1453I<create> is the time it takes to create a socket pair (which is
1360nontrivial) and two watchers: an I/O watcher and a timeout watcher. 1454nontrivial) and two watchers: an I/O watcher and a timeout watcher.
1361 1455
1362I<request>, the most important value, is the time it takes to handle a 1456I<request>, the most important value, is the time it takes to handle a
1363single "request", that is, reading the token from the pipe and forwarding 1457single "request", that is, reading the token from the pipe and forwarding
1364it to another server. This includes deleting the old timeout and creating 1458it to another server. This includes deleting the old timeout and creating
1437speed most when you have lots of watchers, not when you only have a few of 1531speed most when you have lots of watchers, not when you only have a few of
1438them). 1532them).
1439 1533
1440EV is again fastest. 1534EV is again fastest.
1441 1535
1442Perl again comes second. It is noticably faster than the C-based event 1536Perl again comes second. It is noticeably faster than the C-based event
1443loops Event and Glib, although the difference is too small to really 1537loops Event and Glib, although the difference is too small to really
1444matter. 1538matter.
1445 1539
1446POE also performs much better in this case, but is is still far behind the 1540POE also performs much better in this case, but is is still far behind the
1447others. 1541others.
1487probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1581probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1488 1582
1489 1583
1490=head1 SEE ALSO 1584=head1 SEE ALSO
1491 1585
1586Utility functions: L<AnyEvent::Util>.
1587
1492Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>, 1588Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>,
1493L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 1589L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
1494 1590
1495Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 1591Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
1496L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 1592L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
1497L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 1593L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
1498L<AnyEvent::Impl::POE>. 1594L<AnyEvent::Impl::POE>.
1499 1595
1596Non-blocking file handles, sockets, TCP clients and
1597servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>.
1598
1599Asynchronous DNS: L<AnyEvent::DNS>.
1600
1500Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>, 1601Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>,
1501 1602
1502Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1603Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1503 1604
1504 1605
1505=head1 AUTHOR 1606=head1 AUTHOR
1506 1607
1507 Marc Lehmann <schmorp@schmorp.de> 1608 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines