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.82 by root, Fri Apr 25 13:32:39 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.
151 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.
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.
153It is not allowed to close a file handle as long as any watcher is active 156You must not close a file handle as long as any watcher is active on the
154on the underlying 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 162
170 173
171You can create a time watcher by calling the C<< AnyEvent->timer >> 174You can create a time watcher by calling the C<< AnyEvent->timer >>
172method with the following mandatory arguments: 175method with the following mandatory arguments:
173 176
174C<after> specifies after how many seconds (fractional values are 177C<after> specifies after how many seconds (fractional values are
175supported) 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
176case. 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.
177 184
178The 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
179timer 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
180and Glib). 187and Glib).
181 188
226 233
227You 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
228I<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
229be invoked whenever a signal occurs. 236be invoked whenever a signal occurs.
230 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
231Multiple signal occurances can be clumped together into one callback 242Multiple signal occurances can be clumped together into one callback
232invocation, and callback invocation will be synchronous. synchronous means 243invocation, and callback invocation will be synchronous. synchronous means
233that 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,
234but it is guarenteed not to interrupt any other callbacks. 245but it is guarenteed not to interrupt any other callbacks.
235 246
249 260
250The 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
251watches for any child process exit). The watcher will trigger as often 262watches for any child process exit). The watcher will trigger as often
252as 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
253signal 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
254and 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.
255 267
256There 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
257I<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
258have exited already (and no SIGCHLD will be sent anymore). 270have exited already (and no SIGCHLD will be sent anymore).
259 271
444might chose the wrong one unless you load the correct one yourself. 456might chose the wrong one unless you load the correct one yourself.
445 457
446You can chose to use a rather inefficient pure-perl implementation by 458You can chose to use a rather inefficient pure-perl implementation by
447loading the C<AnyEvent::Impl::Perl> module, which gives you similar 459loading the C<AnyEvent::Impl::Perl> module, which gives you similar
448behaviour 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
449 533
450=cut 534=cut
451 535
452package AnyEvent; 536package AnyEvent;
453 537
881 }); 965 });
882 966
883 $quit->wait; 967 $quit->wait;
884 968
885 969
886=head1 BENCHMARK 970=head1 BENCHMARKS
887 971
888To 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
889over 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
890speed of various event loops), here is a benchmark of various supported 974of various event loops I prepared some benchmarks.
891event models natively and with anyevent. The benchmark creates a lot of 975
892timers (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,
893become writable, which it is), lets them fire exactly once and destroys 981which it is), lets them fire exactly once and destroys them again.
894them again.
895 982
896Rewriting the benchmark to use many different sockets instead of using 983Source code for this benchmark is found as F<eg/bench> in the AnyEvent
897the same filehandle for all I/O watchers results in a much longer runtime 984distribution.
898(socket creation is expensive), but qualitatively the same figures, so it
899was not used.
900 985
901=head2 Explanation of the columns 986=head3 Explanation of the columns
902 987
903I<watcher> is the number of event watchers created/destroyed. Since 988I<watcher> is the number of event watchers created/destroyed. Since
904different event models feature vastly different performances, each event 989different event models feature vastly different performances, each event
905loop 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
906and similar between tested event loop (and keep them from crashing): Glib 991and similar between tested event loop (and keep them from crashing): Glib
922signal the end of this phase. 1007signal the end of this phase.
923 1008
924I<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
925watcher. 1010watcher.
926 1011
927=head2 Results 1012=head3 Results
928 1013
929 name watchers bytes create invoke destroy comment 1014 name watchers bytes create invoke destroy comment
930 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
931 EV/Any 100000 610 3.52 0.91 0.75 EV + AnyEvent watchers 1016 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers
932 CoroEV/Any 100000 610 3.49 0.92 0.75 coroutines + Coro::Signal 1017 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal
933 Perl/Any 100000 513 4.91 0.92 1.15 pure perl implementation 1018 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation
934 Event/Event 16000 523 28.05 21.38 0.86 Event native interface 1019 Event/Event 16000 516 31.88 31.30 0.85 Event native interface
935 Event/Any 16000 943 34.43 20.48 1.39 Event + AnyEvent watchers 1020 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers
936 Glib/Any 16000 1357 96.99 12.55 55.51 quadratic behaviour 1021 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour
937 Tk/Any 2000 1855 27.01 66.61 14.03 SEGV with >> 2000 watchers 1022 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers
938 POE/Event 2000 6644 108.15 768.19 14.33 via POE::Loop::Event 1023 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event
939 POE/Select 2000 6343 94.69 807.65 562.69 via POE::Loop::Select 1024 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select
940 1025
941=head2 Discussion 1026=head3 Discussion
942 1027
943The benchmark does I<not> measure scalability of the event loop very 1028The benchmark does I<not> measure scalability of the event loop very
944well. 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)
945can 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
946file descriptors grows high. In this benchmark, all events become ready at 1031file descriptors grows high. In this benchmark, all events become ready at
947the same time, so select/poll-based implementations get an unnatural speed 1032the same time, so select/poll-based implementations get an unnatural speed
948boost. 1033boost.
949 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
950C<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
951maximal/minimal, respectively. Even when going through AnyEvent, there are 1046maximal/minimal, respectively. Even when going through AnyEvent, it uses
952only two event loops that use slightly less memory (the C<Event> module 1047far less memory than any other event loop and is still faster than Event
953natively and the pure perl backend), and no faster event models, not even 1048natively.
954C<Event> natively.
955 1049
956The 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
957zero 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
958interpreter and the backend itself, and all watchers become ready at the 1052interpreter and the backend itself). Nevertheless this shows that it
959same time). Nevertheless this shows that it adds very little overhead in 1053adds very little overhead in itself. Like any select-based backend its
960itself. Like any select-based backend its performance becomes really bad 1054performance becomes really bad with lots of file descriptors (and few of
961with lots of file descriptors (and few of them active), of course, but 1055them active), of course, but this was not subject of this benchmark.
962this was not subject of this benchmark.
963 1056
964The C<Event> module has a relatively high setup and callback invocation cost, 1057The C<Event> module has a relatively high setup and callback invocation
965but overall scores on the third place. 1058cost, but overall scores in on the third place.
966 1059
967C<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
968faster callback invocation and overall ends up in the same class as 1061faster callback invocation and overall ends up in the same class as
969C<Event>. However, Glib scales extremely badly, doubling the number of 1062C<Event>. However, Glib scales extremely badly, doubling the number of
970watchers increases the processing time by more than a factor of four, 1063watchers increases the processing time by more than a factor of four,
971making it completely unusable when using larger numbers of watchers 1064making it completely unusable when using larger numbers of watchers
972(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
975The 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
976more than 2000 watchers is a big setback, however, as correctness takes 1069more than 2000 watchers is a big setback, however, as correctness takes
977precedence over speed. Nevertheless, its performance is surprising, as the 1070precedence over speed. Nevertheless, its performance is surprising, as the
978file 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()
979employed 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
980hidden 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
981figures above). 1074above).
982 1075
983C<POE>, regardless of underlying event loop (wether using its pure perl 1076C<POE>, regardless of underlying event loop (whether using its pure
984select-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
985memory usage: Watchers use almost 30 times as much memory as EV watchers, 1079and memory usage: Watchers use almost 30 times as much memory as
986and 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
987invocation is almost 900 times slower than with AnyEvent's pure perl 1082invocation speed is almost 900 times slower than with AnyEvent's pure perl
988implementation. The design of the POE adaptor class in AnyEvent can not 1083implementation. The design of the POE adaptor class in AnyEvent can not
989really account for this, as session creation overhead is small compared 1084really account for this, as session creation overhead is small compared
990to execution of the state machine, which is coded pretty optimally within 1085to execution of the state machine, which is coded pretty optimally within
991L<AnyEvent::Impl::POE>. POE simply seems to be abysmally slow. 1086L<AnyEvent::Impl::POE>. POE simply seems to be abysmally slow.
992 1087
993=head2 Summary 1088=head3 Summary
994 1089
1090=over 4
1091
995Using 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
996event 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.
997 1095
998The 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
999the 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
1000adds AnyEvent significant overhead. 1098adds AnyEvent significant overhead.
1001 1099
1002And 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
1003reasonable 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
1004 1230
1005 1231
1006=head1 FORK 1232=head1 FORK
1007 1233
1008Most 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