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.84 by root, Fri Apr 25 13:48:42 2008 UTC vs.
Revision 1.102 by root, Sun Apr 27 21:16:26 2008 UTC

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
68useful) and you want to force your users to use the one and only event 68useful) and you want to force your users to use the one and only event
69model, you should I<not> use this module. 69model, you should I<not> use this module.
70
71 70
72=head1 DESCRIPTION 71=head1 DESCRIPTION
73 72
74L<AnyEvent> provides an identical interface to multiple event loops. This 73L<AnyEvent> provides an identical interface to multiple event loops. This
75allows module authors to utilise an event loop without forcing module 74allows module authors to utilise an event loop without forcing module
141=head2 I/O WATCHERS 140=head2 I/O WATCHERS
142 141
143You can create an I/O watcher by calling the C<< AnyEvent->io >> method 142You can create an I/O watcher by calling the C<< AnyEvent->io >> method
144with the following mandatory key-value pairs as arguments: 143with the following mandatory key-value pairs as arguments:
145 144
146C<fh> the Perl I<file handle> (I<not> file descriptor) to watch for 145C<fh> the Perl I<file handle> (I<not> file descriptor) to watch
147events. C<poll> must be a string that is either C<r> or C<w>, which 146for events. C<poll> must be a string that is either C<r> or C<w>,
148creates a watcher waiting for "r"eadable or "w"ritable events, 147which creates a watcher waiting for "r"eadable or "w"ritable events,
149respectively. C<cb> is the callback to invoke each time the file handle 148respectively. C<cb> is the callback to invoke each time the file handle
150becomes ready. 149becomes ready.
150
151Although the callback might get passed parameters, their value and
152presence is undefined and you cannot rely on them. Portable AnyEvent
153callbacks cannot use arguments passed to I/O watcher callbacks.
151 154
152The I/O watcher might use the underlying file descriptor or a copy of it. 155The I/O watcher might use the underlying file descriptor or a copy of it.
153You must not close a file handle as long as any watcher is active on the 156You must not close a file handle as long as any watcher is active on the
154underlying file descriptor. 157underlying file descriptor.
155 158
156Some event loops issue spurious readyness notifications, so you should 159Some event loops issue spurious readyness notifications, so you should
157always use non-blocking calls when reading/writing from/to your file 160always use non-blocking calls when reading/writing from/to your file
158handles. 161handles.
159
160Although the callback might get passed parameters, their value and
161presence is undefined and you cannot rely on them. Portable AnyEvent
162callbacks cannot use arguments passed to I/O watcher callbacks.
163 162
164Example: 163Example:
165 164
166 # wait for readability of STDIN, then read a line and disable the watcher 165 # wait for readability of STDIN, then read a line and disable the watcher
167 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 166 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
174 173
175You can create a time watcher by calling the C<< AnyEvent->timer >> 174You can create a time watcher by calling the C<< AnyEvent->timer >>
176method with the following mandatory arguments: 175method with the following mandatory arguments:
177 176
178C<after> specifies after how many seconds (fractional values are 177C<after> specifies after how many seconds (fractional values are
179supported) should the timer activate. C<cb> the callback to invoke in that 178supported) the callback should be invoked. C<cb> is the callback to invoke
180case. 179in that case.
180
181Although the callback might get passed parameters, their value and
182presence is undefined and you cannot rely on them. Portable AnyEvent
183callbacks cannot use arguments passed to time watcher callbacks.
181 184
182The timer callback will be invoked at most once: if you want a repeating 185The timer callback will be invoked at most once: if you want a repeating
183timer you have to create a new watcher (this is a limitation by both Tk 186timer you have to create a new watcher (this is a limitation by both Tk
184and Glib). 187and Glib).
185
186Although the callback might get passed parameters, their value and
187presence is undefined and you cannot rely on them. Portable AnyEvent
188callbacks cannot use arguments passed to time watcher callbacks.
189 188
190Example: 189Example:
191 190
192 # fire an event after 7.7 seconds 191 # fire an event after 7.7 seconds
193 my $w = AnyEvent->timer (after => 7.7, cb => sub { 192 my $w = AnyEvent->timer (after => 7.7, cb => sub {
234 233
235You can watch for signals using a signal watcher, C<signal> is the signal 234You can watch for signals using a signal watcher, C<signal> is the signal
236I<name> without any C<SIG> prefix, C<cb> is the Perl callback to 235I<name> without any C<SIG> prefix, C<cb> is the Perl callback to
237be invoked whenever a signal occurs. 236be invoked whenever a signal occurs.
238 237
238Although the callback might get passed parameters, their value and
239presence is undefined and you cannot rely on them. Portable AnyEvent
240callbacks cannot use arguments passed to signal watcher callbacks.
241
239Multiple signal occurances can be clumped together into one callback 242Multiple signal occurances can be clumped together into one callback
240invocation, and callback invocation will be synchronous. synchronous means 243invocation, and callback invocation will be synchronous. synchronous means
241that 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,
242but it is guarenteed not to interrupt any other callbacks. 245but it is guarenteed not to interrupt any other callbacks.
243 246
257 260
258The child process is specified by the C<pid> argument (if set to C<0>, it 261The child process is specified by the C<pid> argument (if set to C<0>, it
259watches for any child process exit). The watcher will trigger as often 262watches for any child process exit). The watcher will trigger as often
260as status change for the child are received. This works by installing a 263as status change for the child are received. This works by installing a
261signal handler for C<SIGCHLD>. The callback will be called with the pid 264signal handler for C<SIGCHLD>. The callback will be called with the pid
262and exit status (as returned by waitpid). 265and exit status (as returned by waitpid), so unlike other watcher types,
266you I<can> rely on child watcher callback arguments.
263 267
264There is a slight catch to child watchers, however: you usually start them 268There is a slight catch to child watchers, however: you usually start them
265I<after> the child process was created, and this means the process could 269I<after> the child process was created, and this means the process could
266have exited already (and no SIGCHLD will be sent anymore). 270have exited already (and no SIGCHLD will be sent anymore).
267 271
452might chose the wrong one unless you load the correct one yourself. 456might chose the wrong one unless you load the correct one yourself.
453 457
454You can chose to use a rather inefficient pure-perl implementation by 458You can chose to use a rather inefficient pure-perl implementation by
455loading the C<AnyEvent::Impl::Perl> module, which gives you similar 459loading the C<AnyEvent::Impl::Perl> module, which gives you similar
456behaviour everywhere, but letting AnyEvent chose is generally better. 460behaviour everywhere, but letting AnyEvent chose is generally better.
461
462=head1 OTHER MODULES
463
464The following is a non-exhaustive list of additional modules that use
465AnyEvent and can therefore be mixed easily with other AnyEvent modules
466in the same program. Some of the modules come with AnyEvent, some are
467available via CPAN.
468
469=over 4
470
471=item L<AnyEvent::Util>
472
473Contains various utility functions that replace often-used but blocking
474functions such as C<inet_aton> by event-/callback-based versions.
475
476=item L<AnyEvent::Handle>
477
478Provide read and write buffers and manages watchers for reads and writes.
479
480=item L<AnyEvent::Socket>
481
482Provides a means to do non-blocking connects, accepts etc.
483
484=item L<AnyEvent::HTTPD>
485
486Provides a simple web application server framework.
487
488=item L<AnyEvent::DNS>
489
490Provides asynchronous DNS resolver capabilities, beyond what
491L<AnyEvent::Util> offers.
492
493=item L<AnyEvent::FastPing>
494
495The fastest ping in the west.
496
497=item L<Net::IRC3>
498
499AnyEvent based IRC client module family.
500
501=item L<Net::XMPP2>
502
503AnyEvent based XMPP (Jabber protocol) module family.
504
505=item L<Net::FCP>
506
507AnyEvent-based implementation of the Freenet Client Protocol, birthplace
508of AnyEvent.
509
510=item L<Event::ExecFlow>
511
512High level API for event-based execution flow control.
513
514=item L<Coro>
515
516Has special support for AnyEvent.
517
518=item L<IO::Lambda>
519
520The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
521
522=item L<IO::AIO>
523
524Truly asynchronous I/O, should be in the toolbox of every event
525programmer. Can be trivially made to use AnyEvent.
526
527=item L<BDB>
528
529Truly asynchronous Berkeley DB access. Can be trivially made to use
530AnyEvent.
531
532=back
457 533
458=cut 534=cut
459 535
460package AnyEvent; 536package AnyEvent;
461 537
889 }); 965 });
890 966
891 $quit->wait; 967 $quit->wait;
892 968
893 969
894=head1 BENCHMARK 970=head1 BENCHMARKS
895 971
896To give you an idea of the performance and overheads that AnyEvent adds 972To give you an idea of the performance and overheads that AnyEvent adds
897over the event loops themselves (and to give you an impression of the 973over the event loops themselves and to give you an impression of the speed
898speed of various event loops), here is a benchmark of various supported 974of various event loops I prepared some benchmarks.
899event models natively and with anyevent. The benchmark creates a lot of 975
900timers (with a zero timeout) and I/O watchers (watching STDOUT, a pty, to 976=head2 BENCHMARKING ANYEVENT OVERHEAD
977
978Here is a benchmark of various supported event models used natively and
979through anyevent. The benchmark creates a lot of timers (with a zero
980timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
901become writable, which it is), lets them fire exactly once and destroys 981which it is), lets them fire exactly once and destroys them again.
902them again.
903 982
904Rewriting the benchmark to use many different sockets instead of using 983Source code for this benchmark is found as F<eg/bench> in the AnyEvent
905the same filehandle for all I/O watchers results in a much longer runtime 984distribution.
906(socket creation is expensive), but qualitatively the same figures, so it
907was not used.
908 985
909=head2 Explanation of the columns 986=head3 Explanation of the columns
910 987
911I<watcher> is the number of event watchers created/destroyed. Since 988I<watcher> is the number of event watchers created/destroyed. Since
912different event models feature vastly different performances, each event 989different event models feature vastly different performances, each event
913loop was given a number of watchers so that overall runtime is acceptable 990loop was given a number of watchers so that overall runtime is acceptable
914and similar between tested event loop (and keep them from crashing): Glib 991and similar between tested event loop (and keep them from crashing): Glib
930signal the end of this phase. 1007signal the end of this phase.
931 1008
932I<destroy> is the time, in microseconds, that it takes to destroy a single 1009I<destroy> is the time, in microseconds, that it takes to destroy a single
933watcher. 1010watcher.
934 1011
935=head2 Results 1012=head3 Results
936 1013
937 name watchers bytes create invoke destroy comment 1014 name watchers bytes create invoke destroy comment
938 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1015 EV/EV 400000 244 0.56 0.46 0.31 EV native interface
939 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers 1016 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers
940 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal 1017 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal
941 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation 1018 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation
942 Event/Event 16000 516 31.88 31.30 0.85 Event native interface 1019 Event/Event 16000 516 31.88 31.30 0.85 Event native interface
943 Event/Any 16000 936 39.17 33.63 1.43 Event + AnyEvent watchers 1020 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers
944 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour 1021 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour
945 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers 1022 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers
946 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event 1023 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event
947 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select 1024 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select
948 1025
949=head2 Discussion 1026=head3 Discussion
950 1027
951The benchmark does I<not> measure scalability of the event loop very 1028The benchmark does I<not> measure scalability of the event loop very
952well. For example, a select-based event loop (such as the pure perl one) 1029well. For example, a select-based event loop (such as the pure perl one)
953can never compete with an event loop that uses epoll when the number of 1030can never compete with an event loop that uses epoll when the number of
954file descriptors grows high. In this benchmark, all events become ready at 1031file descriptors grows high. In this benchmark, all events become ready at
955the same time, so select/poll-based implementations get an unnatural speed 1032the same time, so select/poll-based implementations get an unnatural speed
956boost. 1033boost.
957 1034
1035Also, note that the number of watchers usually has a nonlinear effect on
1036overall speed, that is, creating twice as many watchers doesn't take twice
1037the time - usually it takes longer. This puts event loops tested with a
1038higher number of watchers at a disadvantage.
1039
1040To put the range of results into perspective, consider that on the
1041benchmark machine, handling an event takes roughly 1600 CPU cycles with
1042EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 CPU
1043cycles with POE.
1044
958C<EV> is the sole leader regarding speed and memory use, which are both 1045C<EV> is the sole leader regarding speed and memory use, which are both
959maximal/minimal, respectively. Even when going through AnyEvent, it uses 1046maximal/minimal, respectively. Even when going through AnyEvent, it uses
960far less memory than any other event loop and is still faster than Event 1047far less memory than any other event loop and is still faster than Event
961natively. 1048natively.
962 1049
963The pure perl implementation is hit in a few sweet spots (both the 1050The pure perl implementation is hit in a few sweet spots (both the
964zero timeout and the use of a single fd hit optimisations in the perl 1051constant timeout and the use of a single fd hit optimisations in the perl
965interpreter and the backend itself, and all watchers become ready at the 1052interpreter and the backend itself). Nevertheless this shows that it
966same time). Nevertheless this shows that it adds very little overhead in 1053adds very little overhead in itself. Like any select-based backend its
967itself. Like any select-based backend its performance becomes really bad 1054performance becomes really bad with lots of file descriptors (and few of
968with lots of file descriptors (and few of them active), of course, but 1055them active), of course, but this was not subject of this benchmark.
969this was not subject of this benchmark.
970 1056
971The C<Event> module has a relatively high setup and callback invocation cost, 1057The C<Event> module has a relatively high setup and callback invocation
972but overall scores on the third place. 1058cost, but overall scores in on the third place.
973 1059
974C<Glib>'s memory usage is quite a bit bit higher, but it features a 1060C<Glib>'s memory usage is quite a bit higher, but it features a
975faster callback invocation and overall ends up in the same class as 1061faster callback invocation and overall ends up in the same class as
976C<Event>. However, Glib scales extremely badly, doubling the number of 1062C<Event>. However, Glib scales extremely badly, doubling the number of
977watchers increases the processing time by more than a factor of four, 1063watchers increases the processing time by more than a factor of four,
978making it completely unusable when using larger numbers of watchers 1064making it completely unusable when using larger numbers of watchers
979(note that only a single file descriptor was used in the benchmark, so 1065(note that only a single file descriptor was used in the benchmark, so
982The C<Tk> adaptor works relatively well. The fact that it crashes with 1068The C<Tk> adaptor works relatively well. The fact that it crashes with
983more than 2000 watchers is a big setback, however, as correctness takes 1069more than 2000 watchers is a big setback, however, as correctness takes
984precedence over speed. Nevertheless, its performance is surprising, as the 1070precedence over speed. Nevertheless, its performance is surprising, as the
985file descriptor is dup()ed for each watcher. This shows that the dup() 1071file descriptor is dup()ed for each watcher. This shows that the dup()
986employed by some adaptors is not a big performance issue (it does incur a 1072employed by some adaptors is not a big performance issue (it does incur a
987hidden memory cost inside the kernel, though, that is not reflected in the 1073hidden memory cost inside the kernel which is not reflected in the figures
988figures above). 1074above).
989 1075
990C<POE>, regardless of underlying event loop (wether using its pure perl 1076C<POE>, regardless of underlying event loop (whether using its pure
991select-based backend or the Event module) shows abysmal performance and 1077perl select-based backend or the Event module, the POE-EV backend
1078couldn't be tested because it wasn't working) shows abysmal performance
992memory usage: Watchers use almost 30 times as much memory as EV watchers, 1079and memory usage: Watchers use almost 30 times as much memory as
993and 10 times as much memory as both Event or EV via AnyEvent. Watcher 1080EV watchers, and 10 times as much memory as Event (the high memory
1081requirements are caused by requiring a session for each watcher). Watcher
994invocation is almost 900 times slower than with AnyEvent's pure perl 1082invocation speed is almost 900 times slower than with AnyEvent's pure perl
995implementation. The design of the POE adaptor class in AnyEvent can not 1083implementation. The design of the POE adaptor class in AnyEvent can not
996really account for this, as session creation overhead is small compared 1084really account for this, as session creation overhead is small compared
997to execution of the state machine, which is coded pretty optimally within 1085to execution of the state machine, which is coded pretty optimally within
998L<AnyEvent::Impl::POE>. POE simply seems to be abysmally slow. 1086L<AnyEvent::Impl::POE>. POE simply seems to be abysmally slow.
999 1087
1000=head2 Summary 1088=head3 Summary
1001 1089
1090=over 4
1091
1002Using EV through AnyEvent is faster than any other event loop, but most 1092=item * Using EV through AnyEvent is faster than any other event loop
1003event loops have acceptable performance with or without AnyEvent. 1093(even when used without AnyEvent), but most event loops have acceptable
1094performance with or without AnyEvent.
1004 1095
1005The overhead AnyEvent adds is usually much smaller than the overhead of 1096=item * The overhead AnyEvent adds is usually much smaller than the overhead of
1006the actual event loop, only with extremely fast event loops such as the EV 1097the actual event loop, only with extremely fast event loops such as EV
1007adds AnyEvent significant overhead. 1098adds AnyEvent significant overhead.
1008 1099
1009And you should simply avoid POE like the plague if you want performance or 1100=item * You should avoid POE like the plague if you want performance or
1010reasonable memory usage. 1101reasonable memory usage.
1102
1103=back
1104
1105=head2 BENCHMARKING THE LARGE SERVER CASE
1106
1107This benchmark atcually benchmarks the event loop itself. It works by
1108creating a number of "servers": each server consists of a socketpair, a
1109timeout watcher that gets reset on activity (but never fires), and an I/O
1110watcher waiting for input on one side of the socket. Each time the socket
1111watcher reads a byte it will write that byte to a random other "server".
1112
1113The effect is that there will be a lot of I/O watchers, only part of which
1114are active at any one point (so there is a constant number of active
1115fds for each loop iterstaion, but which fds these are is random). The
1116timeout is reset each time something is read because that reflects how
1117most timeouts work (and puts extra pressure on the event loops).
1118
1119In this benchmark, we use 10000 socketpairs (20000 sockets), of which 100
1120(1%) are active. This mirrors the activity of large servers with many
1121connections, most of which are idle at any one point in time.
1122
1123Source code for this benchmark is found as F<eg/bench2> in the AnyEvent
1124distribution.
1125
1126=head3 Explanation of the columns
1127
1128I<sockets> is the number of sockets, and twice the number of "servers" (as
1129each server has a read and write socket end).
1130
1131I<create> is the time it takes to create a socketpair (which is
1132nontrivial) and two watchers: an I/O watcher and a timeout watcher.
1133
1134I<request>, the most important value, is the time it takes to handle a
1135single "request", that is, reading the token from the pipe and forwarding
1136it to another server. This includes deleting the old timeout and creating
1137a new one that moves the timeout into the future.
1138
1139=head3 Results
1140
1141 name sockets create request
1142 EV 20000 69.01 11.16
1143 Perl 20000 73.32 35.87
1144 Event 20000 212.62 257.32
1145 Glib 20000 651.16 1896.30
1146 POE 20000 349.67 12317.24 uses POE::Loop::Event
1147
1148=head3 Discussion
1149
1150This benchmark I<does> measure scalability and overall performance of the
1151particular event loop.
1152
1153EV is again fastest. Since it is using epoll on my system, the setup time
1154is relatively high, though.
1155
1156Perl surprisingly comes second. It is much faster than the C-based event
1157loops Event and Glib.
1158
1159Event suffers from high setup time as well (look at its code and you will
1160understand why). Callback invocation also has a high overhead compared to
1161the C<< $_->() for .. >>-style loop that the Perl event loop uses. Event
1162uses select or poll in basically all documented configurations.
1163
1164Glib is hit hard by its quadratic behaviour w.r.t. many watchers. It
1165clearly fails to perform with many filehandles or in busy servers.
1166
1167POE is still completely out of the picture, taking over 1000 times as long
1168as EV, and over 100 times as long as the Perl implementation, even though
1169it uses a C-based event loop in this case.
1170
1171=head3 Summary
1172
1173=over 4
1174
1175=item * The pure perl implementation performs extremely well, considering
1176that it uses select.
1177
1178=item * Avoid Glib or POE in large projects where performance matters.
1179
1180=back
1181
1182=head2 BENCHMARKING SMALL SERVERS
1183
1184While event loops should scale (and select-based ones do not...) even to
1185large servers, most programs we (or I :) actually write have only a few
1186I/O watchers.
1187
1188In this benchmark, I use the same benchmark program as in the large server
1189case, but it uses only eight "servers", of which three are active at any
1190one time. This should reflect performance for a small server relatively
1191well.
1192
1193The columns are identical to the previous table.
1194
1195=head3 Results
1196
1197 name sockets create request
1198 EV 16 20.00 6.54
1199 Perl 16 25.75 12.62
1200 Event 16 81.27 35.86
1201 Glib 16 32.63 15.48
1202 POE 16 261.87 276.28 uses POE::Loop::Event
1203
1204=head3 Discussion
1205
1206The benchmark tries to test the performance of a typical small
1207server. While knowing how various event loops perform is interesting, keep
1208in mind that their overhead in this case is usually not as important, due
1209to the small absolute number of watchers (that is, you need efficiency and
1210speed most when you have lots of watchers, not when you only have a few of
1211them).
1212
1213EV is again fastest.
1214
1215Perl again comes second. It is noticably faster than the C-based event
1216loops Event and Glib, although the difference is too small to really
1217matter.
1218
1219POE also performs much better in this case, but is is still far behind the
1220others.
1221
1222=head3 Summary
1223
1224=over 4
1225
1226=item * C-based event loops perform very well with small number of
1227watchers, as the management overhead dominates.
1228
1229=back
1011 1230
1012 1231
1013=head1 FORK 1232=head1 FORK
1014 1233
1015Most event libraries are not fork-safe. The ones who are usually are 1234Most event libraries are not fork-safe. The ones who are usually are

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines