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

Comparing EV/README (file contents):
Revision 1.36 by root, Thu Oct 21 02:46:59 2010 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 54
55BEFORE YOU START USING THIS MODULE 55BEFORE YOU START USING THIS MODULE
56 If you only need timer, I/O, signal, child and idle watchers and not the 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, 57 advanced functionality of this module, consider using AnyEvent instead,
58 specifically the simplified API described in AE. 58 specifically the simplified API described in AE.
… …
75 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
76 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)
77 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
78 in Perl. 78 in Perl.
79 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
80 MODULE EXPORTS 110 MODULE EXPORTS
81 This module does not export any symbols. 111 This module does not export any symbols.
82 112
83EVENT LOOPS 113EVENT LOOPS
84 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"
… …
121 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
122 continuing the event loop. An alternative is to use 152 continuing the event loop. An alternative is to use
123 "EV::FLAG_FORKCHECK" which calls this function automatically, at 153 "EV::FLAG_FORKCHECK" which calls this function automatically, at
124 some performance loss (refer to the libev documentation). 154 some performance loss (refer to the libev documentation).
125 155
126 $loop->loop_verify 156 $loop->verify
127 Calls "ev_verify" to make internal consistency checks (for debugging 157 Calls "ev_verify" to make internal consistency checks (for debugging
128 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
129 corrupted. 159 corrupted.
130 160
131 $loop = EV::default_loop [$flags] 161 $loop = EV::default_loop [$flags]
… …
203 $backend = EV::backend 233 $backend = EV::backend
204 $backend = $loop->backend 234 $backend = $loop->backend
205 Returns an integer describing the backend used by libev 235 Returns an integer describing the backend used by libev
206 (EV::BACKEND_SELECT or EV::BACKEND_EPOLL). 236 (EV::BACKEND_SELECT or EV::BACKEND_EPOLL).
207 237
208 EV::loop [$flags] 238 $active = EV::run [$flags]
209 $loop->loop ([$flags]) 239 $active = $loop->run ([$flags])
210 Begin checking for events and calling callbacks. It returns when a 240 Begin checking for events and calling callbacks. It returns when a
211 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".
212 246
213 The $flags argument can be one of the following: 247 The $flags argument can be one of the following:
214 248
215 0 as above 249 0 as above
216 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)
217 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)
218 252
219 EV::unloop [$how] 253 EV::break [$how]
220 $loop->unloop ([$how]) 254 $loop->break ([$how])
221 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
222 makes the innermost call to EV::loop return. 256 the innermost call to EV::loop return.
223 257
224 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
225 EV::loop will return as fast as possible. 259 will return as fast as possible.
226 260
227 $count = EV::loop_count 261 When called with an argument of EV::BREAK_CANCEL, any pending break
228 $count = $loop->loop_count 262 will be cancelled.
263
264 $count = EV::iteration
265 $count = $loop->iteration
229 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.
230 Sometimes useful as a generation counter. 267 Sometimes useful as a generation counter.
231 268
232 EV::once $fh_or_undef, $events, $timeout, $cb->($revents) 269 EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
233 $loop->once ($fh_or_undef, $events, $timeout, $cb->($revents)) 270 $loop->once ($fh_or_undef, $events, $timeout, $cb->($revents))
… …
239 "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
240 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
241 "undef" for $fh_or_undef and 0 for $events). 278 "undef" for $fh_or_undef and 0 for $events).
242 279
243 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.
244 Otherwise a EV::timer with this value will be started. 281 Otherwise an "EV::timer" with this value will be started.
245 282
246 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,
247 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
248 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",
249 "EV::READ", "EV::WRITE" and "EV::TIMER"). 286 "EV::READ", "EV::WRITE" and "EV::TIMER").
250 287
251 EV::once doesn't return anything: the watchers stay active till 288 EV::once doesn't return anything: the watchers stay active till
252 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
253 the callback invoked. 290 the callback invoked.
254 291
255 EV::feed_fd_event ($fd, $revents) 292 EV::feed_fd_event $fd, $revents
256 $loop->feed_fd_event ($fd, $revents) 293 $loop->feed_fd_event ($fd, $revents)
257 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
258 call as if the readyness notifications specified by $revents (a 295 call as if the readyness notifications specified by $revents (a
259 combination of "EV::READ" and "EV::WRITE") happened on the file 296 combination of "EV::READ" and "EV::WRITE") happened on the file
260 descriptor $fd. 297 descriptor $fd.
261 298
262 EV::feed_signal_event ($signal) 299 EV::feed_signal_event $signal
263 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
264 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.
265 307
266 EV::set_io_collect_interval $time 308 EV::set_io_collect_interval $time
267 $loop->set_io_collect_interval ($time) 309 $loop->set_io_collect_interval ($time)
268 EV::set_timeout_collect_interval $time 310 EV::set_timeout_collect_interval $time
269 $loop->set_timeout_collect_interval ($time) 311 $loop->set_timeout_collect_interval ($time)
… …
440 TIMER WATCHERS - relative and optionally repeating timeouts 482 TIMER WATCHERS - relative and optionally repeating timeouts
441 $w = EV::timer $after, $repeat, $callback 483 $w = EV::timer $after, $repeat, $callback
442 $w = EV::timer_ns $after, $repeat, $callback 484 $w = EV::timer_ns $after, $repeat, $callback
443 $w = $loop->timer ($after, $repeat, $callback) 485 $w = $loop->timer ($after, $repeat, $callback)
444 $w = $loop->timer_ns ($after, $repeat, $callback) 486 $w = $loop->timer_ns ($after, $repeat, $callback)
445 Calls the callback after $after seconds (which may be fractional). 487 Calls the callback after $after seconds (which may be fractional or
446 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
447 $repeat value as $after) after the callback returns. 489 the $repeat value as $after) after the callback returns.
448 490
449 This means that the callback would be called roughly after $after 491 This means that the callback would be called roughly after $after
450 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
451 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
452 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
… …
459 the same time. 501 the same time.
460 502
461 The "timer_ns" variant doesn't start (activate) the newly created 503 The "timer_ns" variant doesn't start (activate) the newly created
462 watcher. 504 watcher.
463 505
464 $w->set ($after, $repeat) 506 $w->set ($after, $repeat = 0)
465 Reconfigures the watcher, see the constructor above for details. Can 507 Reconfigures the watcher, see the constructor above for details. Can
466 be called at any time. 508 be called at any time.
467 509
468 $w->again 510 $w->again
511 $w->again ($repeat)
469 Similar to the "start" method, but has special semantics for 512 Similar to the "start" method, but has special semantics for
470 repeating timers: 513 repeating timers:
471 514
472 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.
473 516
… …
481 524
482 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
483 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
484 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"
485 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.
486 535
487 PERIODIC WATCHERS - to cron or not to cron? 536 PERIODIC WATCHERS - to cron or not to cron?
488 $w = EV::periodic $at, $interval, $reschedule_cb, $callback 537 $w = EV::periodic $at, $interval, $reschedule_cb, $callback
489 $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback 538 $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
490 $w = $loop->periodic ($at, $interval, $reschedule_cb, $callback) 539 $w = $loop->periodic ($at, $interval, $reschedule_cb, $callback)
… …
507 system time reaches or surpasses this time. 556 system time reaches or surpasses this time.
508 557
509 * repeating interval timer ($interval > 0, $reschedule_cb = 0) 558 * repeating interval timer ($interval > 0, $reschedule_cb = 0)
510 559
511 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
512 the next "$at + N * $interval" time (for some integer N) and 561 the next "$at + N * $interval" time (for the lowest integer N)
513 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.
514 564
515 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
516 to system time: 566 to system time:
517 567
518 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" };
519 569
520 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
521 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
522 system time shows a full hour (UTC). 572 system time shows a full hour (UTC).
523 573
524 Another way to think about it (for the mathematically inclined) 574 Another way to think about it (for the mathematically inclined)
525 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
526 at the next possible time where "$time = $at (mod $interval)", 576 at the next possible time where "$time = $at (mod $interval)",
… …
534 first, and the current time as second argument. 584 first, and the current time as second argument.
535 585
536 *This callback MUST NOT stop or destroy this or any other 586 *This callback MUST NOT stop or destroy this or any other
537 periodic watcher, ever, and MUST NOT call any event loop 587 periodic watcher, ever, and MUST NOT call any event loop
538 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
539 stop it afterwards. You may create and start a "EV::prepare" 589 stop it afterwards. You may create and start an "EV::prepare"
540 watcher for this task. 590 watcher for this task.
541 591
542 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
543 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
544 to to the second argument). It will usually be called just 594 to to the second argument). It will usually be called just
545 before the callback will be triggered, but might be called at 595 before the callback will be triggered, but might be called at
546 other times, too. 596 other times, too.
547 597
548 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
549 that triggers on each midnight, local time (actually 24 hours 599 that triggers on each midnight, local time (actually one day
550 after the last midnight, to keep the example simple. If you know 600 after the last midnight, to keep the example simple):
551 a way to do it correctly in about the same space (without
552 requiring elaborate modules), drop me a note :):
553 601
554 my $daily = EV::periodic 0, 0, sub { 602 my $daily = EV::periodic 0, 0, sub {
555 my ($w, $now) = @_; 603 my ($w, $now) = @_;
556 604
557 use Time::Local (); 605 use Time::Local ();
558 my (undef, undef, undef, $d, $m, $y) = localtime $now; 606 my (undef, undef, undef, $d, $m, $y) = localtime $now;
559 86400 + Time::Local::timelocal 0, 0, 0, $d, $m, $y 607 Time::Local::timelocal_nocheck 0, 0, 0, $d + 1, $m, $y
560 }, sub { 608 }, sub {
561 print "it's midnight or likely shortly after, now\n"; 609 print "it's midnight or likely shortly after, now\n";
562 }; 610 };
563 611
564 The "periodic_ns" variant doesn't start (activate) the newly created 612 The "periodic_ns" variant doesn't start (activate) the newly created
… …
766 $w = $loop->check_ns ($callback) 814 $w = $loop->check_ns ($callback)
767 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
768 has gathered events), but before any other callbacks have been 816 has gathered events), but before any other callbacks have been
769 invoked. 817 invoked.
770 818
771 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
772 mainloop: You register a prepare callback and in there, you create 820 mainloop: You register a prepare callback and in there, you create
773 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
774 real-world example of integrating Net::SNMP (with some details left 822 real-world example of integrating Net::SNMP (with some details left
775 out): 823 out):
776 824
… …
812 watchers are destroyed before this can happen (remember EV::check 860 watchers are destroyed before this can happen (remember EV::check
813 gets called first). 861 gets called first).
814 862
815 The "check_ns" variant doesn't start (activate) the newly created 863 The "check_ns" variant doesn't start (activate) the newly created
816 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.
817 874
818 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
819 Fork watchers are called when a "fork ()" was detected. The invocation 876 Fork watchers are called when a "fork ()" was detected. The invocation
820 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
821 are being called, and only in the child after the fork. 878 are being called, and only in the child after the fork.
… …
878 935
879 Please see the libev documentation for further details. 936 Please see the libev documentation for further details.
880 937
881 $w = EV::async $callback 938 $w = EV::async $callback
882 $w = EV::async_ns $callback 939 $w = EV::async_ns $callback
940 $w = $loop->async ($callback)
941 $w = $loop->async_ns ($callback)
883 $w->send 942 $w->send
884 $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.
885 948
886PERL SIGNALS 949PERL SIGNALS
887 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
888 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
889 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
… …
923 986
924 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
925 course. 988 course.
926 989
927SEE ALSO 990SEE ALSO
928 EV::ADNS (asynchronous DNS), Glib::EV (makes Glib/Gtk2 use EV as event 991 EV::MakeMaker - MakeMaker interface to XS API, EV::ADNS (asynchronous
929 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
930 with EV), Net::SNMP::EV (asynchronous SNMP), AnyEvent for event-loop 993 Glib into EV), Coro::EV (efficient thread integration), Net::SNMP::EV
931 agnostic and portable event driven programming. 994 (asynchronous SNMP), AnyEvent for event-loop agnostic and portable event
995 driven programming.
932 996
933AUTHOR 997AUTHOR
934 Marc Lehmann <schmorp@schmorp.de> 998 Marc Lehmann <schmorp@schmorp.de>
935 http://home.schmorp.de/ 999 http://home.schmorp.de/
936 1000

Diff Legend

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