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.127 by root, Sat May 24 01:15:19 2008 UTC vs.
Revision 1.130 by root, Sat May 24 17:21:50 2008 UTC

… …
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.
317 317
318Condition variables are similar to callbacks, except that you can 318Condition variables are similar to callbacks, except that you can
319optionally wait for them. They can also be called merge points - points 319optionally wait for them. They can also be called merge points - points
320in time where multiple outstandign events have been processed. And yet 320in time where multiple outstanding events have been processed. And yet
321another way to call them is transations - each condition variable can be 321another way to call them is transactions - each condition variable can be
322used to represent a transaction, which finishes at some point and delivers 322used to represent a transaction, which finishes at some point and delivers
323a result. 323a result.
324 324
325Condition variables are very useful to signal that something has finished, 325Condition variables are very useful to signal that something has finished,
326for example, if you write a module that does asynchronous http requests, 326for example, if you write a module that does asynchronous http requests,
… …
332you can block your main program until an event occurs - for example, you 332you can block your main program until an event occurs - for example, you
333could C<< ->recv >> in your main program until the user clicks the Quit 333could C<< ->recv >> in your main program until the user clicks the Quit
334button of your app, which would C<< ->send >> the "quit" event. 334button of your app, which would C<< ->send >> the "quit" event.
335 335
336Note that condition variables recurse into the event loop - if you have 336Note 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 337two 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 338lose. Therefore, condition variables are good to export to your caller, but
339you should avoid making a blocking wait yourself, at least in callbacks, 339you should avoid making a blocking wait yourself, at least in callbacks,
340as this asks for trouble. 340as this asks for trouble.
341 341
342Condition variables are represented by hash refs in perl, and the keys 342Condition variables are represented by hash refs in perl, and the keys
… …
443doesn't execute once). 443doesn't execute once).
444 444
445This is the general pattern when you "fan out" into multiple subrequests: 445This is the general pattern when you "fan out" into multiple subrequests:
446use an outer C<begin>/C<end> pair to set the callback and ensure C<end> 446use an outer C<begin>/C<end> pair to set the callback and ensure C<end>
447is called at least once, and then, for each subrequest you start, call 447is called at least once, and then, for each subrequest you start, call
448C<begin> and for eahc subrequest you finish, call C<end>. 448C<begin> and for each subrequest you finish, call C<end>.
449 449
450=back 450=back
451 451
452=head3 METHODS FOR CONSUMERS 452=head3 METHODS FOR CONSUMERS
453 453
… …
475(programs might want to do that to stay interactive), so I<if you are 475(programs might want to do that to stay interactive), so I<if you are
476using this from a module, never require a blocking wait>, but let the 476using this from a module, never require a blocking wait>, but let the
477caller decide whether the call will block or not (for example, by coupling 477caller decide whether the call will block or not (for example, by coupling
478condition variables with some kind of request results and supporting 478condition variables with some kind of request results and supporting
479callbacks so the caller knows that getting the result will not block, 479callbacks so the caller knows that getting the result will not block,
480while still suppporting blocking waits if the caller so desires). 480while still supporting blocking waits if the caller so desires).
481 481
482Another reason I<never> to C<< ->recv >> in a module is that you cannot 482Another reason I<never> to C<< ->recv >> in a module is that you cannot
483sensibly have two C<< ->recv >>'s in parallel, as that would require 483sensibly have two C<< ->recv >>'s in parallel, as that would require
484multiple interpreters or coroutines/threads, none of which C<AnyEvent> 484multiple interpreters or coroutines/threads, none of which C<AnyEvent>
485can supply. 485can supply.
… …
696no warnings; 696no warnings;
697use strict; 697use strict;
698 698
699use Carp; 699use Carp;
700 700
701our $VERSION = '3.6'; 701our $VERSION = '4.0';
702our $MODEL; 702our $MODEL;
703 703
704our $AUTOLOAD; 704our $AUTOLOAD;
705our @ISA; 705our @ISA;
706 706
… …
1029model it chooses. 1029model it chooses.
1030 1030
1031=item C<PERL_ANYEVENT_MODEL> 1031=item C<PERL_ANYEVENT_MODEL>
1032 1032
1033This can be used to specify the event model to be used by AnyEvent, before 1033This can be used to specify the event model to be used by AnyEvent, before
1034autodetection and -probing kicks in. It must be a string consisting 1034auto detection and -probing kicks in. It must be a string consisting
1035entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended 1035entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
1036and the resulting module name is loaded and if the load was successful, 1036and the resulting module name is loaded and if the load was successful,
1037used as event model. If it fails to load AnyEvent will proceed with 1037used as event model. If it fails to load AnyEvent will proceed with
1038autodetection and -probing. 1038auto detection and -probing.
1039 1039
1040This functionality might change in future versions. 1040This functionality might change in future versions.
1041 1041
1042For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you 1042For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1043could start your program like this: 1043could start your program like this:
… …
1046 1046
1047=item C<PERL_ANYEVENT_PROTOCOLS> 1047=item C<PERL_ANYEVENT_PROTOCOLS>
1048 1048
1049Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences 1049Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1050for IPv4 or IPv6. The default is unspecified (and might change, or be the result 1050for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1051of autoprobing). 1051of auto probing).
1052 1052
1053Must be set to a comma-separated list of protocols or address families, 1053Must be set to a comma-separated list of protocols or address families,
1054current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be 1054current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1055used, and preference will be given to protocols mentioned earlier in the 1055used, and preference will be given to protocols mentioned earlier in the
1056list. 1056list.
… …
1060small, as the program has to handle connection errors already- 1060small, as the program has to handle connection errors already-
1061 1061
1062Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6, 1062Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1063but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4> 1063but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1064- only support IPv4, never try to resolve or contact IPv6 1064- only support IPv4, never try to resolve or contact IPv6
1065addressses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 1065addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1066IPv6, but prefer IPv6 over IPv4. 1066IPv6, but prefer IPv6 over IPv4.
1067 1067
1068=item C<PERL_ANYEVENT_EDNS0> 1068=item C<PERL_ANYEVENT_EDNS0>
1069 1069
1070Used by L<AnyEvent::DNS> to decide wether to use the EDNS0 extension 1070Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
1071for DNS. This extension is generally useful to reduce DNS traffic, but 1071for DNS. This extension is generally useful to reduce DNS traffic, but
1072some (broken) firewalls drop such DNS packets, which is why it is off by 1072some (broken) firewalls drop such DNS packets, which is why it is off by
1073default. 1073default.
1074 1074
1075Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 1075Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
… …
1167 syswrite $txn->{fh}, $txn->{request} 1167 syswrite $txn->{fh}, $txn->{request}
1168 or die "connection or write error"; 1168 or die "connection or write error";
1169 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r }); 1169 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r });
1170 1170
1171Again, C<fh_ready_r> waits till all data has arrived, and then stores the 1171Again, C<fh_ready_r> waits till all data has arrived, and then stores the
1172result and signals any possible waiters that the request ahs finished: 1172result and signals any possible waiters that the request has finished:
1173 1173
1174 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 1174 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
1175 1175
1176 if (end-of-file or data complete) { 1176 if (end-of-file or data complete) {
1177 $txn->{result} = $txn->{buf}; 1177 $txn->{result} = $txn->{buf};
… …
1185 1185
1186 $txn->{finished}->recv; 1186 $txn->{finished}->recv;
1187 return $txn->{result}; 1187 return $txn->{result};
1188 1188
1189The actual code goes further and collects all errors (C<die>s, exceptions) 1189The actual code goes further and collects all errors (C<die>s, exceptions)
1190that occured during request processing. The C<result> method detects 1190that occurred during request processing. The C<result> method detects
1191whether an exception as thrown (it is stored inside the $txn object) 1191whether an exception as thrown (it is stored inside the $txn object)
1192and just throws the exception, which means connection errors and other 1192and just throws the exception, which means connection errors and other
1193problems get reported tot he code that tries to use the result, not in a 1193problems get reported tot he code that tries to use the result, not in a
1194random callback. 1194random callback.
1195 1195
… …
1241of various event loops I prepared some benchmarks. 1241of various event loops I prepared some benchmarks.
1242 1242
1243=head2 BENCHMARKING ANYEVENT OVERHEAD 1243=head2 BENCHMARKING ANYEVENT OVERHEAD
1244 1244
1245Here is a benchmark of various supported event models used natively and 1245Here is a benchmark of various supported event models used natively and
1246through anyevent. The benchmark creates a lot of timers (with a zero 1246through AnyEvent. The benchmark creates a lot of timers (with a zero
1247timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 1247timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
1248which it is), lets them fire exactly once and destroys them again. 1248which it is), lets them fire exactly once and destroys them again.
1249 1249
1250Source code for this benchmark is found as F<eg/bench> in the AnyEvent 1250Source code for this benchmark is found as F<eg/bench> in the AnyEvent
1251distribution. 1251distribution.
… …
1374 1374
1375=back 1375=back
1376 1376
1377=head2 BENCHMARKING THE LARGE SERVER CASE 1377=head2 BENCHMARKING THE LARGE SERVER CASE
1378 1378
1379This benchmark atcually benchmarks the event loop itself. It works by 1379This benchmark actually benchmarks the event loop itself. It works by
1380creating a number of "servers": each server consists of a socketpair, a 1380creating a number of "servers": each server consists of a socket pair, a
1381timeout watcher that gets reset on activity (but never fires), and an I/O 1381timeout watcher that gets reset on activity (but never fires), and an I/O
1382watcher waiting for input on one side of the socket. Each time the socket 1382watcher waiting for input on one side of the socket. Each time the socket
1383watcher reads a byte it will write that byte to a random other "server". 1383watcher reads a byte it will write that byte to a random other "server".
1384 1384
1385The effect is that there will be a lot of I/O watchers, only part of which 1385The effect is that there will be a lot of I/O watchers, only part of which
1386are active at any one point (so there is a constant number of active 1386are active at any one point (so there is a constant number of active
1387fds for each loop iterstaion, but which fds these are is random). The 1387fds for each loop iteration, but which fds these are is random). The
1388timeout is reset each time something is read because that reflects how 1388timeout is reset each time something is read because that reflects how
1389most timeouts work (and puts extra pressure on the event loops). 1389most timeouts work (and puts extra pressure on the event loops).
1390 1390
1391In this benchmark, we use 10000 socketpairs (20000 sockets), of which 100 1391In this benchmark, we use 10000 socket pairs (20000 sockets), of which 100
1392(1%) are active. This mirrors the activity of large servers with many 1392(1%) are active. This mirrors the activity of large servers with many
1393connections, most of which are idle at any one point in time. 1393connections, most of which are idle at any one point in time.
1394 1394
1395Source code for this benchmark is found as F<eg/bench2> in the AnyEvent 1395Source code for this benchmark is found as F<eg/bench2> in the AnyEvent
1396distribution. 1396distribution.
… …
1398=head3 Explanation of the columns 1398=head3 Explanation of the columns
1399 1399
1400I<sockets> is the number of sockets, and twice the number of "servers" (as 1400I<sockets> is the number of sockets, and twice the number of "servers" (as
1401each server has a read and write socket end). 1401each server has a read and write socket end).
1402 1402
1403I<create> is the time it takes to create a socketpair (which is 1403I<create> is the time it takes to create a socket pair (which is
1404nontrivial) and two watchers: an I/O watcher and a timeout watcher. 1404nontrivial) and two watchers: an I/O watcher and a timeout watcher.
1405 1405
1406I<request>, the most important value, is the time it takes to handle a 1406I<request>, the most important value, is the time it takes to handle a
1407single "request", that is, reading the token from the pipe and forwarding 1407single "request", that is, reading the token from the pipe and forwarding
1408it to another server. This includes deleting the old timeout and creating 1408it to another server. This includes deleting the old timeout and creating
… …
1481speed most when you have lots of watchers, not when you only have a few of 1481speed most when you have lots of watchers, not when you only have a few of
1482them). 1482them).
1483 1483
1484EV is again fastest. 1484EV is again fastest.
1485 1485
1486Perl again comes second. It is noticably faster than the C-based event 1486Perl again comes second. It is noticeably faster than the C-based event
1487loops Event and Glib, although the difference is too small to really 1487loops Event and Glib, although the difference is too small to really
1488matter. 1488matter.
1489 1489
1490POE also performs much better in this case, but is is still far behind the 1490POE also performs much better in this case, but is is still far behind the
1491others. 1491others.

Diff Legend

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