ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/README
(Generate patch)

Comparing AnyEvent/README (file contents):
Revision 1.32 by root, Fri Oct 3 07:19:23 2008 UTC vs.
Revision 1.37 by root, Mon Apr 20 14:34:18 2009 UTC

… …
132 These watchers are normal Perl objects with normal Perl lifetime. After 132 These watchers are normal Perl objects with normal Perl lifetime. After
133 creating a watcher it will immediately "watch" for events and invoke the 133 creating a watcher it will immediately "watch" for events and invoke the
134 callback when the event occurs (of course, only when the event model is 134 callback when the event occurs (of course, only when the event model is
135 in control). 135 in control).
136 136
137 Note that callbacks must not permanently change global variables
138 potentially in use by the event loop (such as $_ or $[) and that
139 callbacks must not "die". The former is good programming practise in
140 Perl and the latter stems from the fact that exception handling differs
141 widely between event loops.
142
137 To disable the watcher you have to destroy it (e.g. by setting the 143 To disable the watcher you have to destroy it (e.g. by setting the
138 variable you store it in to "undef" or otherwise deleting all references 144 variable you store it in to "undef" or otherwise deleting all references
139 to it). 145 to it).
140 146
141 All watchers are created by calling a method on the "AnyEvent" class. 147 All watchers are created by calling a method on the "AnyEvent" class.
… …
156 162
157 I/O WATCHERS 163 I/O WATCHERS
158 You can create an I/O watcher by calling the "AnyEvent->io" method with 164 You can create an I/O watcher by calling the "AnyEvent->io" method with
159 the following mandatory key-value pairs as arguments: 165 the following mandatory key-value pairs as arguments:
160 166
161 "fh" the Perl *file handle* (*not* file descriptor) to watch for events 167 "fh" is the Perl *file handle* (*not* file descriptor) to watch for
162 (AnyEvent might or might not keep a reference to this file handle). 168 events (AnyEvent might or might not keep a reference to this file
169 handle). Note that only file handles pointing to things for which
170 non-blocking operation makes sense are allowed. This includes sockets,
171 most character devices, pipes, fifos and so on, but not for example
172 files or block devices.
173
163 "poll" must be a string that is either "r" or "w", which creates a 174 "poll" must be a string that is either "r" or "w", which creates a
164 watcher waiting for "r"eadable or "w"ritable events, respectively. "cb" 175 watcher waiting for "r"eadable or "w"ritable events, respectively.
176
165 is the callback to invoke each time the file handle becomes ready. 177 "cb" is the callback to invoke each time the file handle becomes ready.
166 178
167 Although the callback might get passed parameters, their value and 179 Although the callback might get passed parameters, their value and
168 presence is undefined and you cannot rely on them. Portable AnyEvent 180 presence is undefined and you cannot rely on them. Portable AnyEvent
169 callbacks cannot use arguments passed to I/O watcher callbacks. 181 callbacks cannot use arguments passed to I/O watcher callbacks.
170 182
… …
301 313
302 In either case, if you care (and in most cases, you don't), then you 314 In either case, if you care (and in most cases, you don't), then you
303 can get whatever behaviour you want with any event loop, by taking 315 can get whatever behaviour you want with any event loop, by taking
304 the difference between "AnyEvent->time" and "AnyEvent->now" into 316 the difference between "AnyEvent->time" and "AnyEvent->now" into
305 account. 317 account.
318
319 AnyEvent->now_update
320 Some event loops (such as EV or AnyEvent::Impl::Perl) cache the
321 current time for each loop iteration (see the discussion of
322 AnyEvent->now, above).
323
324 When a callback runs for a long time (or when the process sleeps),
325 then this "current" time will differ substantially from the real
326 time, which might affect timers and time-outs.
327
328 When this is the case, you can call this method, which will update
329 the event loop's idea of "current time".
330
331 Note that updating the time *might* cause some events to be handled.
306 332
307 SIGNAL WATCHERS 333 SIGNAL WATCHERS
308 You can watch for signals using a signal watcher, "signal" is the signal 334 You can watch for signals using a signal watcher, "signal" is the signal
309 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl 335 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl
310 callback to be invoked whenever a signal occurs. 336 callback to be invoked whenever a signal occurs.
… …
870 mentioned will be used, and preference will be given to protocols 896 mentioned will be used, and preference will be given to protocols
871 mentioned earlier in the list. 897 mentioned earlier in the list.
872 898
873 This variable can effectively be used for denial-of-service attacks 899 This variable can effectively be used for denial-of-service attacks
874 against local programs (e.g. when setuid), although the impact is 900 against local programs (e.g. when setuid), although the impact is
875 likely small, as the program has to handle connection errors 901 likely small, as the program has to handle conenction and other
876 already- 902 failures anyways.
877 903
878 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over 904 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
879 IPv6, but support both and try to use both. 905 IPv6, but support both and try to use both.
880 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to 906 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
881 resolve or contact IPv6 addresses. 907 resolve or contact IPv6 addresses.
… …
1131 *destroy* is the time, in microseconds, that it takes to destroy a 1157 *destroy* is the time, in microseconds, that it takes to destroy a
1132 single watcher. 1158 single watcher.
1133 1159
1134 Results 1160 Results
1135 name watchers bytes create invoke destroy comment 1161 name watchers bytes create invoke destroy comment
1136 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1162 EV/EV 400000 224 0.47 0.35 0.27 EV native interface
1137 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers 1163 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
1138 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal 1164 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
1139 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation 1165 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
1140 Event/Event 16000 516 31.88 31.30 0.85 Event native interface 1166 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
1141 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers 1167 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
1142 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour 1168 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
1143 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers 1169 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
1144 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event 1170 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
1145 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select 1171 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
1146 1172
1147 Discussion 1173 Discussion
1148 The benchmark does *not* measure scalability of the event loop very 1174 The benchmark does *not* measure scalability of the event loop very
1149 well. For example, a select-based event loop (such as the pure perl one) 1175 well. For example, a select-based event loop (such as the pure perl one)
1150 can never compete with an event loop that uses epoll when the number of 1176 can never compete with an event loop that uses epoll when the number of
… …
1387 1413
1388BUGS 1414BUGS
1389 Perl 5.8 has numerous memleaks that sometimes hit this module and are 1415 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1390 hard to work around. If you suffer from memleaks, first upgrade to Perl 1416 hard to work around. If you suffer from memleaks, first upgrade to Perl
1391 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other 1417 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
1392 annoying mamleaks, such as leaking on "map" and "grep" but it is usually 1418 annoying memleaks, such as leaking on "map" and "grep" but it is usually
1393 not as pronounced). 1419 not as pronounced).
1394 1420
1395SEE ALSO 1421SEE ALSO
1396 Utility functions: AnyEvent::Util. 1422 Utility functions: AnyEvent::Util.
1397 1423

Diff Legend

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