1EV(3) User Contributed Perl Documentation EV(3)
2
6 EV - perl interface to libev, a high performance full-featured event
7 loop
8
10 use EV;
11 # TIMERS
13 my $w = EV::timer 2, 0, sub {
15 warn "is called after 2s";
16 };
17 my $w = EV::timer 2, 2, sub {
19 warn "is called roughly every 2s (repeat = 2)";
20 };
21 undef $w; # destroy event watcher again
23 my $w = EV::periodic 0, 60, 0, sub {
25 warn "is called every minute, on the minute, exactly";
26 };
27 # IO
29 my $w = EV::io *STDIN, EV::READ, sub {
31 my ($w, $revents) = @_; # all callbacks receive the watcher and event mask
32 warn "stdin is readable, you entered: ", <STDIN>;
33 };
34 # SIGNALS
36 my $w = EV::signal 'QUIT', sub {
38 warn "sigquit received\n";
39 };
40 # CHILD/PID STATUS CHANGES
42 my $w = EV::child 666, 0, sub {
44 my ($w, $revents) = @_;
45 my $status = $w->rstatus;
46 };
47 # STAT CHANGES
49 my $w = EV::stat "/etc/passwd", 10, sub {
50 my ($w, $revents) = @_;
51 warn $w->path, " has changed somehow.\n";
52 };
53 # MAINLOOP
55 EV::run; # loop until EV::break is called or all watchers stop
56 EV::run EV::RUN_ONCE; # block until at least one event could be handled
57 EV::run EV::RUN_NOWAIT; # try to handle same events, but do not block
58
60 If you only need timer, I/O, signal, child and idle watchers and not
61 the advanced functionality of this module, consider using AnyEvent
62 instead, specifically the simplified API described in AE.
63 When used with EV as backend, the AE API is as fast as the native EV
65 API, but your programs/modules will still run with many other event
66 loops.
67
69 This module provides an interface to libev
70 (<http://software.schmorp.de/pkg/libev.html>). While the documentation
71 below is comprehensive, one might also consult the documentation of
72 libev itself (<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod> or
73 perldoc EV::libev) for more subtle details on watcher semantics or some
74 discussion on the available backends, or how to force a specific
75 backend with "LIBEV_FLAGS", or just about in any case because it has
76 much more detailed information.
77 This module is very fast and scalable. It is actually so fast that you
79 can use it through the AnyEvent module, stay portable to other event
80 loops (if you don't rely on any watcher types not available through it)
81 and still be faster than with any other event loop currently supported
82 in Perl.
83 PORTING FROM EV 3.X to 4.X
85 EV version 4 introduces a number of incompatible changes summarised
86 here. According to the depreciation strategy used by libev, there is a
87 compatibility layer in place so programs should continue to run
88 unchanged (the XS interface lacks this layer, so programs using that
89 one need to be updated).
90 This compatibility layer will be switched off in some future release.
92 All changes relevant to Perl are renames of symbols, functions and
94 methods:
95 EV::loop => EV::run
97 EV::LOOP_NONBLOCK => EV::RUN_NOWAIT
98 EV::LOOP_ONESHOT => EV::RUN_ONCE
99 EV::unloop => EV::break
101 EV::UNLOOP_CANCEL => EV::BREAK_CANCEL
102 EV::UNLOOP_ONE => EV::BREAK_ONE
103 EV::UNLOOP_ALL => EV::BREAK_ALL
104 EV::TIMEOUT => EV::TIMER
106 EV::loop_count => EV::iteration
108 EV::loop_depth => EV::depth
109 EV::loop_verify => EV::verify
110 The loop object methods corresponding to the functions above have been
112 similarly renamed.
113 MODULE EXPORTS
115 This module does not export any symbols.
116
118 EV supports multiple event loops: There is a single "default event
119 loop" that can handle everything including signals and child watchers,
120 and any number of "dynamic event loops" that can use different backends
121 (with various limitations), but no child and signal watchers.
122 You do not have to do anything to create the default event loop: When
124 the module is loaded a suitable backend is selected on the premise of
125 selecting a working backend (which for example rules out kqueue on most
126 BSDs). Modules should, unless they have "special needs" always use the
127 default loop as this is fastest (perl-wise), best supported by other
128 modules (e.g. AnyEvent or Coro) and most portable event loop.
129 For specific programs you can create additional event loops
131 dynamically.
132 If you want to take advantage of kqueue (which often works properly for
134 sockets only) even though the default loop doesn't enable it, you can
135 embed a kqueue loop into the default loop: running the default loop
136 will then also service the kqueue loop to some extent. See the example
137 in the section about embed watchers for an example on how to achieve
138 that.
139 $loop = new EV::Loop [$flags]
141 Create a new event loop as per the specified flags. Please refer to
142 the "ev_loop_new ()" function description in the libev
143 documentation
144 (<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#GLOBAL_FUNCTIONS>,
145 or locally-installed as EV::libev manpage) for more info.
146 The loop will automatically be destroyed when it is no longer
148 referenced by any watcher and the loop object goes out of scope.
149 If you are not embedding the loop, then Using "EV::FLAG_FORKCHECK"
151 is recommended, as only the default event loop is protected by this
152 module. If you are embedding this loop in the default loop, this is
153 not necessary, as "EV::embed" automatically does the right thing on
154 fork.
155 $loop->loop_fork
157 Must be called after a fork in the child, before entering or
158 continuing the event loop. An alternative is to use
159 "EV::FLAG_FORKCHECK" which calls this function automatically, at
160 some performance loss (refer to the libev documentation).
161 $loop->verify
163 Calls "ev_verify" to make internal consistency checks (for
164 debugging libev) and abort the program if any data structures were
165 found to be corrupted.
166 $loop = EV::default_loop [$flags]
168 Return the default loop (which is a singleton object). Since this
169 module already creates the default loop with default flags,
170 specifying flags here will not have any effect unless you destroy
171 the default loop first, which isn't supported. So in short: don't
172 do it, and if you break it, you get to keep the pieces.
173
175 $EV::DIED
176 Must contain a reference to a function that is called when a
177 callback throws an exception (with $@ containing the error). The
178 default prints an informative message and continues.
179 If this callback throws an exception it will be silently ignored.
181 $flags = EV::supported_backends
183 $flags = EV::recommended_backends
184 $flags = EV::embeddable_backends
185 Returns the set (see "EV::BACKEND_*" flags) of backends supported
186 by this instance of EV, the set of recommended backends (supposed
187 to be good) for this platform and the set of embeddable backends
188 (see EMBED WATCHERS).
189 EV::sleep $seconds
191 Block the process for the given number of (fractional) seconds.
192 $time = EV::time
194 Returns the current time in (fractional) seconds since the epoch.
195 $time = EV::now
197 $time = $loop->now
198 Returns the time the last event loop iteration has been started.
199 This is the time that (relative) timers are based on, and referring
200 to it is usually faster then calling EV::time.
201 EV::now_update
203 $loop->now_update
204 Establishes the current time by querying the kernel, updating the
205 time returned by "EV::now" in the progress. This is a costly
206 operation and is usually done automatically within "EV::run".
207 This function is rarely useful, but when some event callback runs
209 for a very long time without entering the event loop, updating
210 libev's idea of the current time is a good idea.
211 EV::suspend
213 $loop->suspend
214 EV::resume
215 $loop->resume
216 These two functions suspend and resume a loop, for use when the
217 loop is not used for a while and timeouts should not be processed.
218 A typical use case would be an interactive program such as a game:
220 When the user presses "^Z" to suspend the game and resumes it an
221 hour later it would be best to handle timeouts as if no time had
222 actually passed while the program was suspended. This can be
223 achieved by calling "suspend" in your "SIGTSTP" handler, sending
224 yourself a "SIGSTOP" and calling "resume" directly afterwards to
225 resume timer processing.
226 Effectively, all "timer" watchers will be delayed by the time spend
228 between "suspend" and "resume", and all "periodic" watchers will be
229 rescheduled (that is, they will lose any events that would have
230 occured while suspended).
231 After calling "suspend" you must not call any function on the given
233 loop other than "resume", and you must not call "resume" without a
234 previous call to "suspend".
235 Calling "suspend"/"resume" has the side effect of updating the
237 event loop time (see "now_update").
238 $backend = EV::backend
240 $backend = $loop->backend
241 Returns an integer describing the backend used by libev
242 (EV::BACKEND_SELECT or EV::BACKEND_EPOLL).
243 $active = EV::run [$flags]
245 $active = $loop->run ([$flags])
246 Begin checking for events and calling callbacks. It returns when a
247 callback calls EV::break or the flags are nonzero (in which case
248 the return value is true) or when there are no active watchers
249 which reference the loop (keepalive is true), in which case the
250 return value will be false. The return value can generally be
251 interpreted as "if true, there is more work left to do".
252 The $flags argument can be one of the following:
254 0 as above
256 EV::RUN_ONCE block at most once (wait, but do not loop)
257 EV::RUN_NOWAIT do not block at all (fetch/handle events but do not wait)
258 EV::break [$how]
260 $loop->break ([$how])
261 When called with no arguments or an argument of EV::BREAK_ONE,
262 makes the innermost call to EV::run return.
263 When called with an argument of EV::BREAK_ALL, all calls to EV::run
265 will return as fast as possible.
266 When called with an argument of EV::BREAK_CANCEL, any pending break
268 will be cancelled.
269 $count = EV::iteration
271 $count = $loop->iteration
272 Return the number of times the event loop has polled for new
273 events. Sometimes useful as a generation counter.
274 EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
276 $loop->once ($fh_or_undef, $events, $timeout, $cb->($revents))
277 This function rolls together an I/O and a timer watcher for a
278 single one-shot event without the need for managing a watcher
279 object.
280 If $fh_or_undef is a filehandle or file descriptor, then $events
282 must be a bitset containing either "EV::READ", "EV::WRITE" or
283 "EV::READ | EV::WRITE", indicating the type of I/O event you want
284 to wait for. If you do not want to wait for some I/O event, specify
285 "undef" for $fh_or_undef and 0 for $events).
286 If timeout is "undef" or negative, then there will be no timeout.
288 Otherwise an "EV::timer" with this value will be started.
289 When an error occurs or either the timeout or I/O watcher triggers,
291 then the callback will be called with the received event set (in
292 general you can expect it to be a combination of "EV::ERROR",
293 "EV::READ", "EV::WRITE" and "EV::TIMER").
294 EV::once doesn't return anything: the watchers stay active till
296 either of them triggers, then they will be stopped and freed, and
297 the callback invoked.
298 EV::feed_fd_event $fd, $revents
300 $loop->feed_fd_event ($fd, $revents)
301 Feed an event on a file descriptor into EV. EV will react to this
302 call as if the readyness notifications specified by $revents (a
303 combination of "EV::READ" and "EV::WRITE") happened on the file
304 descriptor $fd.
305 EV::feed_signal_event $signal
307 Feed a signal event into the default loop. EV will react to this
308 call as if the signal specified by $signal had occured.
309 EV::feed_signal $signal
311 Feed a signal event into EV - unlike "EV::feed_signal_event", this
312 works regardless of which loop has registered the signal, and is
313 mainly useful fro custom signal implementations.
314 EV::set_io_collect_interval $time
316 $loop->set_io_collect_interval ($time)
317 EV::set_timeout_collect_interval $time
318 $loop->set_timeout_collect_interval ($time)
319 These advanced functions set the minimum block interval when
320 polling for I/O events and the minimum wait interval for timer
321 events. See the libev documentation at
322 <http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONTROLLING_THE_EVENT_LOOP>
323 (locally installed as EV::libev) for a more detailed discussion.
324 $count = EV::pending_count
326 $count = $loop->pending_count
327 Returns the number of currently pending watchers.
328 EV::invoke_pending
330 $loop->invoke_pending
331 Invoke all currently pending watchers.
332
334 A watcher is an object that gets created to record your interest in
335 some event. For instance, if you want to wait for STDIN to become
336 readable, you would create an EV::io watcher for that:
337 my $watcher = EV::io *STDIN, EV::READ, sub {
339 my ($watcher, $revents) = @_;
340 warn "yeah, STDIN should now be readable without blocking!\n"
341 };
342 All watchers can be active (waiting for events) or inactive (paused).
344 Only active watchers will have their callbacks invoked. All callbacks
345 will be called with at least two arguments: the watcher and a bitmask
346 of received events.
347 Each watcher type has its associated bit in revents, so you can use the
349 same callback for multiple watchers. The event mask is named after the
350 type, i.e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
351 EV::periodic sets EV::PERIODIC and so on, with the exception of I/O
352 events (which can set both EV::READ and EV::WRITE bits).
353 In the rare case where one wants to create a watcher but not start it
355 at the same time, each constructor has a variant with a trailing "_ns"
356 in its name, e.g. EV::io has a non-starting variant EV::io_ns and so
357 on.
358 Please note that a watcher will automatically be stopped when the
360 watcher object is destroyed, so you need to keep the watcher objects
361 returned by the constructors.
362 Also, all methods changing some aspect of a watcher (->set, ->priority,
364 ->fh and so on) automatically stop and start it again if it is active,
365 which means pending events get lost.
366 COMMON WATCHER METHODS
368 This section lists methods common to all watchers.
369 $w->start
371 Starts a watcher if it isn't active already. Does nothing to an
372 already active watcher. By default, all watchers start out in the
373 active state (see the description of the "_ns" variants if you need
374 stopped watchers).
375 $w->stop
377 Stop a watcher if it is active. Also clear any pending events
378 (events that have been received but that didn't yet result in a
379 callback invocation), regardless of whether the watcher was active
380 or not.
381 $bool = $w->is_active
383 Returns true if the watcher is active, false otherwise.
384 $current_data = $w->data
386 $old_data = $w->data ($new_data)
387 Queries a freely usable data scalar on the watcher and optionally
388 changes it. This is a way to associate custom data with a watcher:
389 my $w = EV::timer 60, 0, sub {
391 warn $_[0]->data;
392 };
393 $w->data ("print me!");
394 $current_cb = $w->cb
396 $old_cb = $w->cb ($new_cb)
397 Queries the callback on the watcher and optionally changes it. You
398 can do this at any time without the watcher restarting.
399 $current_priority = $w->priority
401 $old_priority = $w->priority ($new_priority)
402 Queries the priority on the watcher and optionally changes it.
403 Pending watchers with higher priority will be invoked first. The
404 valid range of priorities lies between EV::MAXPRI (default 2) and
405 EV::MINPRI (default -2). If the priority is outside this range it
406 will automatically be normalised to the nearest valid priority.
407 The default priority of any newly-created watcher is 0.
409 Note that the priority semantics have not yet been fleshed out and
411 are subject to almost certain change.
412 $w->invoke ($revents)
414 Call the callback *now* with the given event mask.
415 $w->feed_event ($revents)
417 Feed some events on this watcher into EV. EV will react to this
418 call as if the watcher had received the given $revents mask.
419 $revents = $w->clear_pending
421 If the watcher is pending, this function clears its pending status
422 and returns its $revents bitset (as if its callback was invoked).
423 If the watcher isn't pending it does nothing and returns 0.
424 $previous_state = $w->keepalive ($bool)
426 Normally, "EV::run" will return when there are no active watchers
427 (which is a "deadlock" because no progress can be made anymore).
428 This is convenient because it allows you to start your watchers
429 (and your jobs), call "EV::run" once and when it returns you know
430 that all your jobs are finished (or they forgot to register some
431 watchers for their task :).
432 Sometimes, however, this gets in your way, for example when the
434 module that calls "EV::run" (usually the main program) is not the
435 same module as a long-living watcher (for example a DNS client
436 module written by somebody else even). Then you might want any
437 outstanding requests to be handled, but you would not want to keep
438 "EV::run" from returning just because you happen to have this long-
439 running UDP port watcher.
440 In this case you can clear the keepalive status, which means that
442 even though your watcher is active, it won't keep "EV::run" from
443 returning.
444 The initial value for keepalive is true (enabled), and you can
446 change it any time.
447 Example: Register an I/O watcher for some UDP socket but do not
449 keep the event loop from running just because of that watcher.
450 my $udp_socket = ...
452 my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
453 $udp_watcher->keepalive (0);
454 $loop = $w->loop
456 Return the loop that this watcher is attached to.
457
459 Each of the following subsections describes a single watcher type.
460 I/O WATCHERS - is this file descriptor readable or writable?
462 $w = EV::io $fileno_or_fh, $eventmask, $callback
464 $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
465 $w = $loop->io ($fileno_or_fh, $eventmask, $callback)
466 $w = $loop->io_ns ($fileno_or_fh, $eventmask, $callback)
467 As long as the returned watcher object is alive, call the $callback
468 when at least one of events specified in $eventmask occurs.
469 The $eventmask can be one or more of these constants ORed together:
471 EV::READ wait until read() wouldn't block anymore
473 EV::WRITE wait until write() wouldn't block anymore
474 The "io_ns" variant doesn't start (activate) the newly created
476 watcher.
477 $w->set ($fileno_or_fh, $eventmask)
479 Reconfigures the watcher, see the constructor above for details.
480 Can be called at any time.
481 $current_fh = $w->fh
483 $old_fh = $w->fh ($new_fh)
484 Returns the previously set filehandle and optionally set a new one.
485 $current_eventmask = $w->events
487 $old_eventmask = $w->events ($new_eventmask)
488 Returns the previously set event mask and optionally set a new one.
489 TIMER WATCHERS - relative and optionally repeating timeouts
491 $w = EV::timer $after, $repeat, $callback
493 $w = EV::timer_ns $after, $repeat, $callback
494 $w = $loop->timer ($after, $repeat, $callback)
495 $w = $loop->timer_ns ($after, $repeat, $callback)
496 Calls the callback after $after seconds (which may be fractional or
497 negative). If $repeat is non-zero, the timer will be restarted
498 (with the $repeat value as $after) after the callback returns.
499 This means that the callback would be called roughly after $after
501 seconds, and then every $repeat seconds. The timer does his best
502 not to drift, but it will not invoke the timer more often then once
503 per event loop iteration, and might drift in other cases. If that
504 isn't acceptable, look at EV::periodic, which can provide long-term
505 stable timers.
506 The timer is based on a monotonic clock, that is, if somebody is
508 sitting in front of the machine while the timer is running and
509 changes the system clock, the timer will nevertheless run (roughly)
510 the same time.
511 The "timer_ns" variant doesn't start (activate) the newly created
513 watcher.
514 $w->set ($after, $repeat = 0)
516 Reconfigures the watcher, see the constructor above for details.
517 Can be called at any time.
518 $w->again
520 $w->again ($repeat)
521 Similar to the "start" method, but has special semantics for
522 repeating timers:
523 If the timer is active and non-repeating, it will be stopped.
525 If the timer is active and repeating, reset the timeout to occur
527 $repeat seconds after now.
528 If the timer is inactive and repeating, start it using the repeat
530 value.
531 Otherwise do nothing.
533 This behaviour is useful when you have a timeout for some IO
535 operation. You create a timer object with the same value for $after
536 and $repeat, and then, in the read/write watcher, run the "again"
537 method on the timeout.
538 If called with a $repeat argument, then it uses this a timer repeat
540 value.
541 $after = $w->remaining
543 Calculates and returns the remaining time till the timer will fire.
544 PERIODIC WATCHERS - to cron or not to cron?
546 $w = EV::periodic $at, $interval, $reschedule_cb, $callback
548 $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
549 $w = $loop->periodic ($at, $interval, $reschedule_cb, $callback)
550 $w = $loop->periodic_ns ($at, $interval, $reschedule_cb, $callback)
551 Similar to EV::timer, but is not based on relative timeouts but on
552 absolute times. Apart from creating "simple" timers that trigger
553 "at" the specified time, it can also be used for non-drifting
554 absolute timers and more complex, cron-like, setups that are not
555 adversely affected by time jumps (i.e. when the system clock is
556 changed by explicit date -s or other means such as ntpd). It is
557 also the most complex watcher type in EV.
558 It has three distinct "modes":
560 · absolute timer ($interval = $reschedule_cb = 0)
562 This time simply fires at the wallclock time $at and doesn't
564 repeat. It will not adjust when a time jump occurs, that is, if
565 it is to be run at January 1st 2011 then it will run when the
566 system time reaches or surpasses this time.
567 · repeating interval timer ($interval > 0, $reschedule_cb = 0)
569 In this mode the watcher will always be scheduled to time out
571 at the next "$at + N * $interval" time (for the lowest integer
572 N) and then repeat, regardless of any time jumps. Note that,
573 since "N" can be negative, the first trigger can happen before
574 $at.
575 This can be used to create timers that do not drift with
577 respect to system time:
578 my $hourly = EV::periodic 0, 3600, 0, sub { print "once/hour\n" };
580 That doesn't mean there will always be 3600 seconds in between
582 triggers, but only that the the callback will be called when
583 the system time shows a full hour (UTC).
584 Another way to think about it (for the mathematically inclined)
586 is that EV::periodic will try to run the callback in this mode
587 at the next possible time where "$time = $at (mod $interval)",
588 regardless of any time jumps.
589 · manual reschedule mode ($reschedule_cb = coderef)
591 In this mode $interval and $at are both being ignored. Instead,
593 each time the periodic watcher gets scheduled, the reschedule
594 callback ($reschedule_cb) will be called with the watcher as
595 first, and the current time as second argument.
596 This callback MUST NOT stop or destroy this or any other
598 periodic watcher, ever, and MUST NOT call any event loop
599 functions or methods. If you need to stop it, return 1e30 and
600 stop it afterwards. You may create and start an "EV::prepare"
601 watcher for this task.
602 It must return the next time to trigger, based on the passed
604 time value (that is, the lowest time value larger than or equal
605 to to the second argument). It will usually be called just
606 before the callback will be triggered, but might be called at
607 other times, too.
608 This can be used to create very complex timers, such as a timer
610 that triggers on each midnight, local time (actually one day
611 after the last midnight, to keep the example simple):
612 my $daily = EV::periodic 0, 0, sub {
614 my ($w, $now) = @_;
615 use Time::Local ();
617 my (undef, undef, undef, $d, $m, $y) = localtime $now;
618 Time::Local::timelocal_nocheck 0, 0, 0, $d + 1, $m, $y
619 }, sub {
620 print "it's midnight or likely shortly after, now\n";
621 };
622 The "periodic_ns" variant doesn't start (activate) the newly
624 created watcher.
625 $w->set ($at, $interval, $reschedule_cb)
627 Reconfigures the watcher, see the constructor above for details.
628 Can be called at any time.
629 $w->again
631 Simply stops and starts the watcher again.
632 $time = $w->at
634 Return the time that the watcher is expected to trigger next.
635 SIGNAL WATCHERS - signal me when a signal gets signalled!
637 $w = EV::signal $signal, $callback
639 $w = EV::signal_ns $signal, $callback
640 $w = $loop->signal ($signal, $callback)
641 $w = $loop->signal_ns ($signal, $callback)
642 Call the callback when $signal is received (the signal can be
643 specified by number or by name, just as with "kill" or %SIG).
644 Only one event loop can grab a given signal - attempting to grab
646 the same signal from two EV loops will crash the program
647 immediately or cause data corruption.
648 EV will grab the signal for the process (the kernel only allows one
650 component to receive a signal at a time) when you start a signal
651 watcher, and removes it again when you stop it. Perl does the same
652 when you add/remove callbacks to %SIG, so watch out.
653 You can have as many signal watchers per signal as you want.
655 The "signal_ns" variant doesn't start (activate) the newly created
657 watcher.
658 $w->set ($signal)
660 Reconfigures the watcher, see the constructor above for details.
661 Can be called at any time.
662 $current_signum = $w->signal
664 $old_signum = $w->signal ($new_signal)
665 Returns the previously set signal (always as a number not name) and
666 optionally set a new one.
667 CHILD WATCHERS - watch out for process status changes
669 $w = EV::child $pid, $trace, $callback
671 $w = EV::child_ns $pid, $trace, $callback
672 $w = $loop->child ($pid, $trace, $callback)
673 $w = $loop->child_ns ($pid, $trace, $callback)
674 Call the callback when a status change for pid $pid (or any pid if
675 $pid is 0) has been received (a status change happens when the
676 process terminates or is killed, or, when trace is true,
677 additionally when it is stopped or continued). More precisely: when
678 the process receives a "SIGCHLD", EV will fetch the outstanding
679 exit/wait status for all changed/zombie children and call the
680 callback.
681 It is valid (and fully supported) to install a child watcher after
683 a child has exited but before the event loop has started its next
684 iteration (for example, first you "fork", then the new child
685 process might exit, and only then do you install a child watcher in
686 the parent for the new pid).
687 You can access both exit (or tracing) status and pid by using the
689 "rstatus" and "rpid" methods on the watcher object.
690 You can have as many pid watchers per pid as you want, they will
692 all be called.
693 The "child_ns" variant doesn't start (activate) the newly created
695 watcher.
696 $w->set ($pid, $trace)
698 Reconfigures the watcher, see the constructor above for details.
699 Can be called at any time.
700 $current_pid = $w->pid
702 Returns the previously set process id and optionally set a new one.
703 $exit_status = $w->rstatus
705 Return the exit/wait status (as returned by waitpid, see the
706 waitpid entry in perlfunc).
707 $pid = $w->rpid
709 Return the pid of the awaited child (useful when you have installed
710 a watcher for all pids).
711 STAT WATCHERS - did the file attributes just change?
713 $w = EV::stat $path, $interval, $callback
715 $w = EV::stat_ns $path, $interval, $callback
716 $w = $loop->stat ($path, $interval, $callback)
717 $w = $loop->stat_ns ($path, $interval, $callback)
718 Call the callback when a file status change has been detected on
719 $path. The $path does not need to exist, changing from "path
720 exists" to "path does not exist" is a status change like any other.
721 The $interval is a recommended polling interval for systems where
723 OS-supported change notifications don't exist or are not supported.
724 If you use 0 then an unspecified default is used (which is highly
725 recommended!), which is to be expected to be around five seconds
726 usually.
727 This watcher type is not meant for massive numbers of stat
729 watchers, as even with OS-supported change notifications, this can
730 be resource-intensive.
731 The "stat_ns" variant doesn't start (activate) the newly created
733 watcher.
734 ... = $w->stat
736 This call is very similar to the perl "stat" built-in: It stats
737 (using "lstat") the path specified in the watcher and sets perls
738 stat cache (as well as EV's idea of the current stat values) to the
739 values found.
740 In scalar context, a boolean is return indicating success or
742 failure of the stat. In list context, the same 13-value list as
743 with stat is returned (except that the blksize and blocks fields
744 are not reliable).
745 In the case of an error, errno is set to "ENOENT" (regardless of
747 the actual error value) and the "nlink" value is forced to zero (if
748 the stat was successful then nlink is guaranteed to be non-zero).
749 See also the next two entries for more info.
751 ... = $w->attr
753 Just like "$w->stat", but without the initial stat'ing: this
754 returns the values most recently detected by EV. See the next entry
755 for more info.
756 ... = $w->prev
758 Just like "$w->stat", but without the initial stat'ing: this
759 returns the previous set of values, before the change.
760 That is, when the watcher callback is invoked, "$w->prev" will be
762 set to the values found before a change was detected, while
763 "$w->attr" returns the values found leading to the change
764 detection. The difference (if any) between "prev" and "attr" is
765 what triggered the callback.
766 If you did something to the filesystem object and do not want to
768 trigger yet another change, you can call "stat" to update EV's idea
769 of what the current attributes are.
770 $w->set ($path, $interval)
772 Reconfigures the watcher, see the constructor above for details.
773 Can be called at any time.
774 $current_path = $w->path
776 $old_path = $w->path ($new_path)
777 Returns the previously set path and optionally set a new one.
778 $current_interval = $w->interval
780 $old_interval = $w->interval ($new_interval)
781 Returns the previously set interval and optionally set a new one.
782 Can be used to query the actual interval used.
783 IDLE WATCHERS - when you've got nothing better to do...
785 $w = EV::idle $callback
787 $w = EV::idle_ns $callback
788 $w = $loop->idle ($callback)
789 $w = $loop->idle_ns ($callback)
790 Call the callback when there are no other pending watchers of the
791 same or higher priority (excluding check, prepare and other idle
792 watchers of the same or lower priority, of course). They are called
793 idle watchers because when the watcher is the highest priority
794 pending event in the process, the process is considered to be idle
795 at that priority.
796 If you want a watcher that is only ever called when no other events
798 are outstanding you have to set the priority to "EV::MINPRI".
799 The process will not block as long as any idle watchers are active,
801 and they will be called repeatedly until stopped.
802 For example, if you have idle watchers at priority 0 and 1, and an
804 I/O watcher at priority 0, then the idle watcher at priority 1 and
805 the I/O watcher will always run when ready. Only when the idle
806 watcher at priority 1 is stopped and the I/O watcher at priority 0
807 is not pending with the 0-priority idle watcher be invoked.
808 The "idle_ns" variant doesn't start (activate) the newly created
810 watcher.
811 PREPARE WATCHERS - customise your event loop!
813 $w = EV::prepare $callback
815 $w = EV::prepare_ns $callback
816 $w = $loop->prepare ($callback)
817 $w = $loop->prepare_ns ($callback)
818 Call the callback just before the process would block. You can
819 still create/modify any watchers at this point.
820 See the EV::check watcher, below, for explanations and an example.
822 The "prepare_ns" variant doesn't start (activate) the newly created
824 watcher.
825 CHECK WATCHERS - customise your event loop even more!
827 $w = EV::check $callback
829 $w = EV::check_ns $callback
830 $w = $loop->check ($callback)
831 $w = $loop->check_ns ($callback)
832 Call the callback just after the process wakes up again (after it
833 has gathered events), but before any other callbacks have been
834 invoked.
835 This can be used to integrate other event-based software into the
837 EV mainloop: You register a prepare callback and in there, you
838 create io and timer watchers as required by the other software.
839 Here is a real-world example of integrating Net::SNMP (with some
840 details left out):
841 our @snmp_watcher;
843 our $snmp_prepare = EV::prepare sub {
845 # do nothing unless active
846 $dispatcher->{_event_queue_h}
847 or return;
848 # make the dispatcher handle any outstanding stuff
850 ... not shown
851 # create an I/O watcher for each and every socket
853 @snmp_watcher = (
854 (map { EV::io $_, EV::READ, sub { } }
855 keys %{ $dispatcher->{_descriptors} }),
856 EV::timer +($event->[Net::SNMP::Dispatcher::_ACTIVE]
858 ? $event->[Net::SNMP::Dispatcher::_TIME] - EV::now : 0),
859 0, sub { },
860 );
861 };
862 The callbacks are irrelevant (and are not even being called), the
864 only purpose of those watchers is to wake up the process as soon as
865 one of those events occurs (socket readable, or timer timed out).
866 The corresponding EV::check watcher will then clean up:
867 our $snmp_check = EV::check sub {
869 # destroy all watchers
870 @snmp_watcher = ();
871 # make the dispatcher handle any new stuff
873 ... not shown
874 };
875 The callbacks of the created watchers will not be called as the
877 watchers are destroyed before this can happen (remember EV::check
878 gets called first).
879 The "check_ns" variant doesn't start (activate) the newly created
881 watcher.
882 EV::CHECK constant issues
884 Like all other watcher types, there is a bitmask constant for use
885 in $revents and other places. The "EV::CHECK" is special as it has
886 the same name as the "CHECK" sub called by Perl. This doesn't cause
887 big issues on newer perls (beginning with 5.8.9), but it means
888 thatthe constant must be inlined, i.e. runtime calls will not work.
889 That means that as long as you always "use EV" and then "EV::CHECK"
890 you are on the safe side.
891 FORK WATCHERS - the audacity to resume the event loop after a fork
893 Fork watchers are called when a "fork ()" was detected. The invocation
895 is done before the event loop blocks next and before "check" watchers
896 are being called, and only in the child after the fork.
897 $w = EV::fork $callback
899 $w = EV::fork_ns $callback
900 $w = $loop->fork ($callback)
901 $w = $loop->fork_ns ($callback)
902 Call the callback before the event loop is resumed in the child
903 process after a fork.
904 The "fork_ns" variant doesn't start (activate) the newly created
906 watcher.
907 EMBED WATCHERS - when one backend isn't enough...
909 This is a rather advanced watcher type that lets you embed one event
911 loop into another (currently only IO events are supported in the
912 embedded loop, other types of watchers might be handled in a delayed or
913 incorrect fashion and must not be used).
914 See the libev documentation at
916 <http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_embed_code_when_one_backend_>
917 (locally installed as EV::libev) for more details.
918 In short, this watcher is most useful on BSD systems without working
920 kqueue to still be able to handle a large number of sockets:
921 my $socket_loop;
923 # check wether we use SELECT or POLL _and_ KQUEUE is supported
925 if (
926 (EV::backend & (EV::BACKEND_POLL | EV::BACKEND_SELECT))
927 && (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE)
928 ) {
929 # use kqueue for sockets
930 $socket_loop = new EV::Loop EV::BACKEND_KQUEUE | EV::FLAG_NOENV;
931 }
932 # use the default loop otherwise
934 $socket_loop ||= EV::default_loop;
935 $w = EV::embed $otherloop[, $callback]
937 $w = EV::embed_ns $otherloop[, $callback]
938 $w = $loop->embed ($otherloop[, $callback])
939 $w = $loop->embed_ns ($otherloop[, $callback])
940 Call the callback when the embedded event loop ($otherloop) has any
941 I/O activity. The $callback is optional: if it is missing, then the
942 embedded event loop will be managed automatically (which is
943 recommended), otherwise you have to invoke "sweep" yourself.
944 The "embed_ns" variant doesn't start (activate) the newly created
946 watcher.
947 ASYNC WATCHERS - how to wake up another event loop
949 Async watchers are provided by EV, but have little use in perl
951 directly, as perl neither supports threads running in parallel nor
952 direct access to signal handlers or other contexts where they could be
953 of value.
954 It is, however, possible to use them from the XS level.
956 Please see the libev documentation for further details.
958 $w = EV::async $callback
960 $w = EV::async_ns $callback
961 $w = $loop->async ($callback)
962 $w = $loop->async_ns ($callback)
963 $w->send
964 $bool = $w->async_pending
965 CLEANUP WATCHERS - how to clean up when the event loop goes away
967 Cleanup watchers are not supported on the Perl level, they can only be
969 used via XS currently.
970
972 While Perl signal handling (%SIG) is not affected by EV, the behaviour
973 with EV is as the same as any other C library: Perl-signals will only
974 be handled when Perl runs, which means your signal handler might be
975 invoked only the next time an event callback is invoked.
976 The solution is to use EV signal watchers (see "EV::signal"), which
978 will ensure proper operations with regards to other event watchers.
979 If you cannot do this for whatever reason, you can also force a watcher
981 to be called on every event loop iteration by installing a "EV::check"
982 watcher:
983 my $async_check = EV::check sub { };
985 This ensures that perl gets into control for a short time to handle any
987 pending signals, and also ensures (slightly) slower overall operation.
988
990 Ithreads are not supported by this module in any way. Perl pseudo-
991 threads is evil stuff and must die. Real threads as provided by Coro
992 are fully supported (and enhanced support is available via Coro::EV).
993
995 Most of the "improved" event delivering mechanisms of modern operating
996 systems have quite a few problems with fork(2) (to put it bluntly: it
997 is not supported and usually destructive). Libev makes it possible to
998 work around this by having a function that recreates the kernel state
999 after fork in the child.
1000 On non-win32 platforms, this module requires the pthread_atfork
1002 functionality to do this automatically for you. This function is quite
1003 buggy on most BSDs, though, so YMMV. The overhead for this is quite
1004 negligible, because everything the function currently does is set a
1005 flag that is checked only when the event loop gets used the next time,
1006 so when you do fork but not use EV, the overhead is minimal.
1007 On win32, there is no notion of fork so all this doesn't apply, of
1009 course.
1010
1012 EV::MakeMaker - MakeMaker interface to XS API, EV::ADNS (asynchronous
1013 DNS), Glib::EV (makes Glib/Gtk2 use EV as event loop), EV::Glib (embed
1014 Glib into EV), Coro::EV (efficient thread integration), Net::SNMP::EV
1015 (asynchronous SNMP), AnyEvent for event-loop agnostic and portable
1016 event driven programming.
1017
1019 Marc Lehmann <schmorp@schmorp.de>
1020 http://home.schmorp.de/
1021perl v5.30.0 2019-07-30 EV(3)