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

Comparing EV/README (file contents):
Revision 1.35 by root, Thu Dec 31 06:59:47 2009 UTC vs.
Revision 1.45 by root, Fri Dec 21 07:06:51 2018 UTC

… …
46 my ($w, $revents) = @_; 46 my ($w, $revents) = @_;
47 warn $w->path, " has changed somehow.\n"; 47 warn $w->path, " has changed somehow.\n";
48 }; 48 };
49 49
50 # MAINLOOP 50 # MAINLOOP
51 EV::loop; # loop until EV::unloop is called or all watchers stop 51 EV::run; # loop until EV::break is called or all watchers stop
52 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled 52 EV::run EV::RUN_ONCE; # block until at least one event could be handled
53 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block 53 EV::run EV::RUN_NOWAIT; # try to handle same events, but do not block
54
55BEFORE YOU START USING THIS MODULE
56 If you only need timer, I/O, signal, child and idle watchers and not the
57 advanced functionality of this module, consider using AnyEvent instead,
58 specifically the simplified API described in AE.
59
60 When used with EV as backend, the AE API is as fast as the native EV
61 API, but your programs/modules will still run with many other event
62 loops.
54 63
55DESCRIPTION 64DESCRIPTION
56 This module provides an interface to libev 65 This module provides an interface to libev
57 (<http://software.schmorp.de/pkg/libev.html>). While the documentation 66 (<http://software.schmorp.de/pkg/libev.html>). While the documentation
58 below is comprehensive, one might also consult the documentation of 67 below is comprehensive, one might also consult the documentation of
… …
66 can use it through the AnyEvent module, stay portable to other event 75 can use it through the AnyEvent module, stay portable to other event
67 loops (if you don't rely on any watcher types not available through it) 76 loops (if you don't rely on any watcher types not available through it)
68 and still be faster than with any other event loop currently supported 77 and still be faster than with any other event loop currently supported
69 in Perl. 78 in Perl.
70 79
80 PORTING FROM EV 3.X to 4.X
81 EV version 4 introduces a number of incompatible changes summarised
82 here. According to the depreciation strategy used by libev, there is a
83 compatibility layer in place so programs should continue to run
84 unchanged (the XS interface lacks this layer, so programs using that one
85 need to be updated).
86
87 This compatibility layer will be switched off in some future release.
88
89 All changes relevant to Perl are renames of symbols, functions and
90 methods:
91
92 EV::loop => EV::run
93 EV::LOOP_NONBLOCK => EV::RUN_NOWAIT
94 EV::LOOP_ONESHOT => EV::RUN_ONCE
95
96 EV::unloop => EV::break
97 EV::UNLOOP_CANCEL => EV::BREAK_CANCEL
98 EV::UNLOOP_ONE => EV::BREAK_ONE
99 EV::UNLOOP_ALL => EV::BREAK_ALL
100
101 EV::TIMEOUT => EV::TIMER
102
103 EV::loop_count => EV::iteration
104 EV::loop_depth => EV::depth
105 EV::loop_verify => EV::verify
106
107 The loop object methods corresponding to the functions above have been
108 similarly renamed.
109
71 MODULE EXPORTS 110 MODULE EXPORTS
72 This module does not export any symbols. 111 This module does not export any symbols.
73 112
74EVENT LOOPS 113EVENT LOOPS
75 EV supports multiple event loops: There is a single "default event loop" 114 EV supports multiple event loops: There is a single "default event loop"
… …
112 Must be called after a fork in the child, before entering or 151 Must be called after a fork in the child, before entering or
113 continuing the event loop. An alternative is to use 152 continuing the event loop. An alternative is to use
114 "EV::FLAG_FORKCHECK" which calls this function automatically, at 153 "EV::FLAG_FORKCHECK" which calls this function automatically, at
115 some performance loss (refer to the libev documentation). 154 some performance loss (refer to the libev documentation).
116 155
117 $loop->loop_verify 156 $loop->verify
118 Calls "ev_verify" to make internal consistency checks (for debugging 157 Calls "ev_verify" to make internal consistency checks (for debugging
119 libev) and abort the program if any data structures were found to be 158 libev) and abort the program if any data structures were found to be
120 corrupted. 159 corrupted.
121 160
122 $loop = EV::default_loop [$flags] 161 $loop = EV::default_loop [$flags]
… …
194 $backend = EV::backend 233 $backend = EV::backend
195 $backend = $loop->backend 234 $backend = $loop->backend
196 Returns an integer describing the backend used by libev 235 Returns an integer describing the backend used by libev
197 (EV::BACKEND_SELECT or EV::BACKEND_EPOLL). 236 (EV::BACKEND_SELECT or EV::BACKEND_EPOLL).
198 237
199 EV::loop [$flags] 238 $active = EV::run [$flags]
200 $loop->loop ([$flags]) 239 $active = $loop->run ([$flags])
201 Begin checking for events and calling callbacks. It returns when a 240 Begin checking for events and calling callbacks. It returns when a
202 callback calls EV::unloop. 241 callback calls EV::break or the flags are nonzero (in which case the
242 return value is true) or when there are no active watchers which
243 reference the loop (keepalive is true), in which case the return
244 value will be false. The return value can generally be interpreted
245 as "if true, there is more work left to do".
203 246
204 The $flags argument can be one of the following: 247 The $flags argument can be one of the following:
205 248
206 0 as above 249 0 as above
207 EV::LOOP_ONESHOT block at most once (wait, but do not loop) 250 EV::RUN_ONCE block at most once (wait, but do not loop)
208 EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait) 251 EV::RUN_NOWAIT do not block at all (fetch/handle events but do not wait)
209 252
210 EV::unloop [$how] 253 EV::break [$how]
211 $loop->unloop ([$how]) 254 $loop->break ([$how])
212 When called with no arguments or an argument of EV::UNLOOP_ONE, 255 When called with no arguments or an argument of EV::BREAK_ONE, makes
213 makes the innermost call to EV::loop return. 256 the innermost call to EV::loop return.
214 257
215 When called with an argument of EV::UNLOOP_ALL, all calls to 258 When called with an argument of EV::BREAK_ALL, all calls to EV::loop
216 EV::loop will return as fast as possible. 259 will return as fast as possible.
217 260
218 $count = EV::loop_count 261 When called with an argument of EV::BREAK_CANCEL, any pending break
219 $count = $loop->loop_count 262 will be cancelled.
263
264 $count = EV::iteration
265 $count = $loop->iteration
220 Return the number of times the event loop has polled for new events. 266 Return the number of times the event loop has polled for new events.
221 Sometimes useful as a generation counter. 267 Sometimes useful as a generation counter.
222 268
223 EV::once $fh_or_undef, $events, $timeout, $cb->($revents) 269 EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
224 $loop->once ($fh_or_undef, $events, $timeout, $cb->($revents)) 270 $loop->once ($fh_or_undef, $events, $timeout, $cb->($revents))
… …
230 "EV::READ | EV::WRITE", indicating the type of I/O event you want to 276 "EV::READ | EV::WRITE", indicating the type of I/O event you want to
231 wait for. If you do not want to wait for some I/O event, specify 277 wait for. If you do not want to wait for some I/O event, specify
232 "undef" for $fh_or_undef and 0 for $events). 278 "undef" for $fh_or_undef and 0 for $events).
233 279
234 If timeout is "undef" or negative, then there will be no timeout. 280 If timeout is "undef" or negative, then there will be no timeout.
235 Otherwise a EV::timer with this value will be started. 281 Otherwise an "EV::timer" with this value will be started.
236 282
237 When an error occurs or either the timeout or I/O watcher triggers, 283 When an error occurs or either the timeout or I/O watcher triggers,
238 then the callback will be called with the received event set (in 284 then the callback will be called with the received event set (in
239 general you can expect it to be a combination of "EV::ERROR", 285 general you can expect it to be a combination of "EV::ERROR",
240 "EV::READ", "EV::WRITE" and "EV::TIMEOUT"). 286 "EV::READ", "EV::WRITE" and "EV::TIMER").
241 287
242 EV::once doesn't return anything: the watchers stay active till 288 EV::once doesn't return anything: the watchers stay active till
243 either of them triggers, then they will be stopped and freed, and 289 either of them triggers, then they will be stopped and freed, and
244 the callback invoked. 290 the callback invoked.
245 291
246 EV::feed_fd_event ($fd, $revents) 292 EV::feed_fd_event $fd, $revents
247 $loop->feed_fd_event ($fd, $revents) 293 $loop->feed_fd_event ($fd, $revents)
248 Feed an event on a file descriptor into EV. EV will react to this 294 Feed an event on a file descriptor into EV. EV will react to this
249 call as if the readyness notifications specified by $revents (a 295 call as if the readyness notifications specified by $revents (a
250 combination of "EV::READ" and "EV::WRITE") happened on the file 296 combination of "EV::READ" and "EV::WRITE") happened on the file
251 descriptor $fd. 297 descriptor $fd.
252 298
253 EV::feed_signal_event ($signal) 299 EV::feed_signal_event $signal
254 Feed a signal event into EV. EV will react to this call as if the 300 Feed a signal event into the default loop. EV will react to this
255 signal specified by $signal had occured. 301 call as if the signal specified by $signal had occured.
302
303 EV::feed_signal $signal
304 Feed a signal event into EV - unlike "EV::feed_signal_event", this
305 works regardless of which loop has registered the signal, and is
306 mainly useful fro custom signal implementations.
256 307
257 EV::set_io_collect_interval $time 308 EV::set_io_collect_interval $time
258 $loop->set_io_collect_interval ($time) 309 $loop->set_io_collect_interval ($time)
259 EV::set_timeout_collect_interval $time 310 EV::set_timeout_collect_interval $time
260 $loop->set_timeout_collect_interval ($time) 311 $loop->set_timeout_collect_interval ($time)
… …
290 341
291 Each watcher type has its associated bit in revents, so you can use the 342 Each watcher type has its associated bit in revents, so you can use the
292 same callback for multiple watchers. The event mask is named after the 343 same callback for multiple watchers. The event mask is named after the
293 type, i.e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE, 344 type, i.e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
294 EV::periodic sets EV::PERIODIC and so on, with the exception of I/O 345 EV::periodic sets EV::PERIODIC and so on, with the exception of I/O
295 events (which can set both EV::READ and EV::WRITE bits), and EV::timer 346 events (which can set both EV::READ and EV::WRITE bits).
296 (which uses EV::TIMEOUT).
297 347
298 In the rare case where one wants to create a watcher but not start it at 348 In the rare case where one wants to create a watcher but not start it at
299 the same time, each constructor has a variant with a trailing "_ns" in 349 the same time, each constructor has a variant with a trailing "_ns" in
300 its name, e.g. EV::io has a non-starting variant EV::io_ns and so on. 350 its name, e.g. EV::io has a non-starting variant EV::io_ns and so on.
301 351
… …
432 TIMER WATCHERS - relative and optionally repeating timeouts 482 TIMER WATCHERS - relative and optionally repeating timeouts
433 $w = EV::timer $after, $repeat, $callback 483 $w = EV::timer $after, $repeat, $callback
434 $w = EV::timer_ns $after, $repeat, $callback 484 $w = EV::timer_ns $after, $repeat, $callback
435 $w = $loop->timer ($after, $repeat, $callback) 485 $w = $loop->timer ($after, $repeat, $callback)
436 $w = $loop->timer_ns ($after, $repeat, $callback) 486 $w = $loop->timer_ns ($after, $repeat, $callback)
437 Calls the callback after $after seconds (which may be fractional). 487 Calls the callback after $after seconds (which may be fractional or
438 If $repeat is non-zero, the timer will be restarted (with the 488 negative). If $repeat is non-zero, the timer will be restarted (with
439 $repeat value as $after) after the callback returns. 489 the $repeat value as $after) after the callback returns.
440 490
441 This means that the callback would be called roughly after $after 491 This means that the callback would be called roughly after $after
442 seconds, and then every $repeat seconds. The timer does his best not 492 seconds, and then every $repeat seconds. The timer does his best not
443 to drift, but it will not invoke the timer more often then once per 493 to drift, but it will not invoke the timer more often then once per
444 event loop iteration, and might drift in other cases. If that isn't 494 event loop iteration, and might drift in other cases. If that isn't
… …
451 the same time. 501 the same time.
452 502
453 The "timer_ns" variant doesn't start (activate) the newly created 503 The "timer_ns" variant doesn't start (activate) the newly created
454 watcher. 504 watcher.
455 505
456 $w->set ($after, $repeat) 506 $w->set ($after, $repeat = 0)
457 Reconfigures the watcher, see the constructor above for details. Can 507 Reconfigures the watcher, see the constructor above for details. Can
458 be called at any time. 508 be called at any time.
459 509
460 $w->again 510 $w->again
511 $w->again ($repeat)
461 Similar to the "start" method, but has special semantics for 512 Similar to the "start" method, but has special semantics for
462 repeating timers: 513 repeating timers:
463 514
464 If the timer is active and non-repeating, it will be stopped. 515 If the timer is active and non-repeating, it will be stopped.
465 516
… …
473 524
474 This behaviour is useful when you have a timeout for some IO 525 This behaviour is useful when you have a timeout for some IO
475 operation. You create a timer object with the same value for $after 526 operation. You create a timer object with the same value for $after
476 and $repeat, and then, in the read/write watcher, run the "again" 527 and $repeat, and then, in the read/write watcher, run the "again"
477 method on the timeout. 528 method on the timeout.
529
530 If called with a $repeat argument, then it uses this a timer repeat
531 value.
532
533 $after = $w->remaining
534 Calculates and returns the remaining time till the timer will fire.
478 535
479 PERIODIC WATCHERS - to cron or not to cron? 536 PERIODIC WATCHERS - to cron or not to cron?
480 $w = EV::periodic $at, $interval, $reschedule_cb, $callback 537 $w = EV::periodic $at, $interval, $reschedule_cb, $callback
481 $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback 538 $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
482 $w = $loop->periodic ($at, $interval, $reschedule_cb, $callback) 539 $w = $loop->periodic ($at, $interval, $reschedule_cb, $callback)
… …
499 system time reaches or surpasses this time. 556 system time reaches or surpasses this time.
500 557
501 * repeating interval timer ($interval > 0, $reschedule_cb = 0) 558 * repeating interval timer ($interval > 0, $reschedule_cb = 0)
502 559
503 In this mode the watcher will always be scheduled to time out at 560 In this mode the watcher will always be scheduled to time out at
504 the next "$at + N * $interval" time (for some integer N) and 561 the next "$at + N * $interval" time (for the lowest integer N)
505 then repeat, regardless of any time jumps. 562 and then repeat, regardless of any time jumps. Note that, since
563 "N" can be negative, the first trigger can happen before $at.
506 564
507 This can be used to create timers that do not drift with respect 565 This can be used to create timers that do not drift with respect
508 to system time: 566 to system time:
509 567
510 my $hourly = EV::periodic 0, 3600, 0, sub { print "once/hour\n" }; 568 my $hourly = EV::periodic 0, 3600, 0, sub { print "once/hour\n" };
511 569
512 That doesn't mean there will always be 3600 seconds in between 570 That doesn't mean there will always be 3600 seconds in between
513 triggers, but only that the the clalback will be called when the 571 triggers, but only that the the callback will be called when the
514 system time shows a full hour (UTC). 572 system time shows a full hour (UTC).
515 573
516 Another way to think about it (for the mathematically inclined) 574 Another way to think about it (for the mathematically inclined)
517 is that EV::periodic will try to run the callback in this mode 575 is that EV::periodic will try to run the callback in this mode
518 at the next possible time where "$time = $at (mod $interval)", 576 at the next possible time where "$time = $at (mod $interval)",
… …
526 first, and the current time as second argument. 584 first, and the current time as second argument.
527 585
528 *This callback MUST NOT stop or destroy this or any other 586 *This callback MUST NOT stop or destroy this or any other
529 periodic watcher, ever, and MUST NOT call any event loop 587 periodic watcher, ever, and MUST NOT call any event loop
530 functions or methods*. If you need to stop it, return 1e30 and 588 functions or methods*. If you need to stop it, return 1e30 and
531 stop it afterwards. You may create and start a "EV::prepare" 589 stop it afterwards. You may create and start an "EV::prepare"
532 watcher for this task. 590 watcher for this task.
533 591
534 It must return the next time to trigger, based on the passed 592 It must return the next time to trigger, based on the passed
535 time value (that is, the lowest time value larger than or equal 593 time value (that is, the lowest time value larger than or equal
536 to to the second argument). It will usually be called just 594 to to the second argument). It will usually be called just
537 before the callback will be triggered, but might be called at 595 before the callback will be triggered, but might be called at
538 other times, too. 596 other times, too.
539 597
540 This can be used to create very complex timers, such as a timer 598 This can be used to create very complex timers, such as a timer
541 that triggers on each midnight, local time (actually 24 hours 599 that triggers on each midnight, local time (actually one day
542 after the last midnight, to keep the example simple. If you know 600 after the last midnight, to keep the example simple):
543 a way to do it correctly in about the same space (without
544 requiring elaborate modules), drop me a note :):
545 601
546 my $daily = EV::periodic 0, 0, sub { 602 my $daily = EV::periodic 0, 0, sub {
547 my ($w, $now) = @_; 603 my ($w, $now) = @_;
548 604
549 use Time::Local (); 605 use Time::Local ();
550 my (undef, undef, undef, $d, $m, $y) = localtime $now; 606 my (undef, undef, undef, $d, $m, $y) = localtime $now;
551 86400 + Time::Local::timelocal 0, 0, 0, $d, $m, $y 607 Time::Local::timelocal_nocheck 0, 0, 0, $d + 1, $m, $y
552 }, sub { 608 }, sub {
553 print "it's midnight or likely shortly after, now\n"; 609 print "it's midnight or likely shortly after, now\n";
554 }; 610 };
555 611
556 The "periodic_ns" variant doesn't start (activate) the newly created 612 The "periodic_ns" variant doesn't start (activate) the newly created
… …
758 $w = $loop->check_ns ($callback) 814 $w = $loop->check_ns ($callback)
759 Call the callback just after the process wakes up again (after it 815 Call the callback just after the process wakes up again (after it
760 has gathered events), but before any other callbacks have been 816 has gathered events), but before any other callbacks have been
761 invoked. 817 invoked.
762 818
763 This is used to integrate other event-based software into the EV 819 This can be used to integrate other event-based software into the EV
764 mainloop: You register a prepare callback and in there, you create 820 mainloop: You register a prepare callback and in there, you create
765 io and timer watchers as required by the other software. Here is a 821 io and timer watchers as required by the other software. Here is a
766 real-world example of integrating Net::SNMP (with some details left 822 real-world example of integrating Net::SNMP (with some details left
767 out): 823 out):
768 824
… …
804 watchers are destroyed before this can happen (remember EV::check 860 watchers are destroyed before this can happen (remember EV::check
805 gets called first). 861 gets called first).
806 862
807 The "check_ns" variant doesn't start (activate) the newly created 863 The "check_ns" variant doesn't start (activate) the newly created
808 watcher. 864 watcher.
865
866 EV::CHECK constant issues
867 Like all other watcher types, there is a bitmask constant for use in
868 $revents and other places. The "EV::CHECK" is special as it has the
869 same name as the "CHECK" sub called by Perl. This doesn't cause big
870 issues on newer perls (beginning with 5.8.9), but it means thatthe
871 constant must be *inlined*, i.e. runtime calls will not work. That
872 means that as long as you always "use EV" and then "EV::CHECK" you
873 are on the safe side.
809 874
810 FORK WATCHERS - the audacity to resume the event loop after a fork 875 FORK WATCHERS - the audacity to resume the event loop after a fork
811 Fork watchers are called when a "fork ()" was detected. The invocation 876 Fork watchers are called when a "fork ()" was detected. The invocation
812 is done before the event loop blocks next and before "check" watchers 877 is done before the event loop blocks next and before "check" watchers
813 are being called, and only in the child after the fork. 878 are being called, and only in the child after the fork.
… …
870 935
871 Please see the libev documentation for further details. 936 Please see the libev documentation for further details.
872 937
873 $w = EV::async $callback 938 $w = EV::async $callback
874 $w = EV::async_ns $callback 939 $w = EV::async_ns $callback
940 $w = $loop->async ($callback)
941 $w = $loop->async_ns ($callback)
875 $w->send 942 $w->send
876 $bool = $w->async_pending 943 $bool = $w->async_pending
944
945 CLEANUP WATCHERS - how to clean up when the event loop goes away
946 Cleanup watchers are not supported on the Perl level, they can only be
947 used via XS currently.
877 948
878PERL SIGNALS 949PERL SIGNALS
879 While Perl signal handling (%SIG) is not affected by EV, the behaviour 950 While Perl signal handling (%SIG) is not affected by EV, the behaviour
880 with EV is as the same as any other C library: Perl-signals will only be 951 with EV is as the same as any other C library: Perl-signals will only be
881 handled when Perl runs, which means your signal handler might be invoked 952 handled when Perl runs, which means your signal handler might be invoked
… …
915 986
916 On win32, there is no notion of fork so all this doesn't apply, of 987 On win32, there is no notion of fork so all this doesn't apply, of
917 course. 988 course.
918 989
919SEE ALSO 990SEE ALSO
920 EV::ADNS (asynchronous DNS), Glib::EV (makes Glib/Gtk2 use EV as event 991 EV::MakeMaker - MakeMaker interface to XS API, EV::ADNS (asynchronous
921 loop), EV::Glib (embed Glib into EV), Coro::EV (efficient coroutines 992 DNS), Glib::EV (makes Glib/Gtk2 use EV as event loop), EV::Glib (embed
922 with EV), Net::SNMP::EV (asynchronous SNMP), AnyEvent for event-loop 993 Glib into EV), Coro::EV (efficient thread integration), Net::SNMP::EV
923 agnostic and portable event driven programming. 994 (asynchronous SNMP), AnyEvent for event-loop agnostic and portable event
995 driven programming.
924 996
925AUTHOR 997AUTHOR
926 Marc Lehmann <schmorp@schmorp.de> 998 Marc Lehmann <schmorp@schmorp.de>
927 http://home.schmorp.de/ 999 http://home.schmorp.de/
928 1000

Diff Legend

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