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 for 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 $repeat = $w->repeat
546 $old_repeat = $w->repeat ($new_repeat)
547 Returns the current value of the repeat attribute and optionally
548 sets a new one. Setting the new one will not restart the watcher -
549 if the watcher is active, the new repeat value is used whenever it
550 expires next.
551 PERIODIC WATCHERS - to cron or not to cron?
553 $w = EV::periodic $at, $interval, $reschedule_cb, $callback
555 $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
556 $w = $loop->periodic ($at, $interval, $reschedule_cb, $callback)
557 $w = $loop->periodic_ns ($at, $interval, $reschedule_cb, $callback)
558 Similar to EV::timer, but is not based on relative timeouts but on
559 absolute times. Apart from creating "simple" timers that trigger
560 "at" the specified time, it can also be used for non-drifting
561 absolute timers and more complex, cron-like, setups that are not
562 adversely affected by time jumps (i.e. when the system clock is
563 changed by explicit date -s or other means such as ntpd). It is
564 also the most complex watcher type in EV.
565 It has three distinct "modes":
567 • absolute timer ($interval = $reschedule_cb = 0)
569 This time simply fires at the wallclock time $at and doesn't
571 repeat. It will not adjust when a time jump occurs, that is, if
572 it is to be run at January 1st 2011 then it will run when the
573 system time reaches or surpasses this time.
574 • repeating interval timer ($interval > 0, $reschedule_cb = 0)
576 In this mode the watcher will always be scheduled to time out
578 at the next "$at + N * $interval" time (for the lowest integer
579 N) and then repeat, regardless of any time jumps. Note that,
580 since "N" can be negative, the first trigger can happen before
581 $at.
582 This can be used to create timers that do not drift with
584 respect to system time:
585 my $hourly = EV::periodic 0, 3600, 0, sub { print "once/hour\n" };
587 That doesn't mean there will always be 3600 seconds in between
589 triggers, but only that the the callback will be called when
590 the system time shows a full hour (UTC).
591 Another way to think about it (for the mathematically inclined)
593 is that EV::periodic will try to run the callback in this mode
594 at the next possible time where "$time = $at (mod $interval)",
595 regardless of any time jumps.
596 • manual reschedule mode ($reschedule_cb = coderef)
598 In this mode $interval and $at are both being ignored. Instead,
600 each time the periodic watcher gets scheduled, the reschedule
601 callback ($reschedule_cb) will be called with the watcher as
602 first, and the current time as second argument.
603 This callback MUST NOT stop or destroy this or any other
605 periodic watcher, ever, and MUST NOT call any event loop
606 functions or methods. If you need to stop it, return 1e30 and
607 stop it afterwards. You may create and start an "EV::prepare"
608 watcher for this task.
609 It must return the next time to trigger, based on the passed
611 time value (that is, the lowest time value larger than or equal
612 to to the second argument). It will usually be called just
613 before the callback will be triggered, but might be called at
614 other times, too.
615 This can be used to create very complex timers, such as a timer
617 that triggers on each midnight, local time (actually one day
618 after the last midnight, to keep the example simple):
619 my $daily = EV::periodic 0, 0, sub {
621 my ($w, $now) = @_;
622 use Time::Local ();
624 my (undef, undef, undef, $d, $m, $y) = localtime $now;
625 Time::Local::timelocal_nocheck 0, 0, 0, $d + 1, $m, $y
626 }, sub {
627 print "it's midnight or likely shortly after, now\n";
628 };
629 The "periodic_ns" variant doesn't start (activate) the newly
631 created watcher.
632 $w->set ($at, $interval, $reschedule_cb)
634 Reconfigures the watcher, see the constructor above for details.
635 Can be called at any time.
636 $w->again
638 Simply stops and starts the watcher again.
639 $time = $w->at
641 Return the time that the watcher is expected to trigger next.
642 $offset = $w->offset
644 $old_offset = $w->offset ($new_offset)
645 Returns the current value of the offset attribute and optionally
646 sets a new one. Setting the new one will not restart the watcher -
647 if the watcher is active, the new offset value is used whenever it
648 expires next.
649 $interval = $w->interval
651 $old_interval = $w->interval ($new_interval)
652 See above, for the interval attribute.
653 $reschedule_cb = $w->reschedule_cb
655 $old_reschedule_cb = $w->reschedule_cb ($new_reschedule_cb)
656 See above, for the reschedule callback.
657 SIGNAL WATCHERS - signal me when a signal gets signalled!
659 $w = EV::signal $signal, $callback
661 $w = EV::signal_ns $signal, $callback
662 $w = $loop->signal ($signal, $callback)
663 $w = $loop->signal_ns ($signal, $callback)
664 Call the callback when $signal is received (the signal can be
665 specified by number or by name, just as with "kill" or %SIG).
666 Only one event loop can grab a given signal - attempting to grab
668 the same signal from two EV loops will crash the program
669 immediately or cause data corruption.
670 EV will grab the signal for the process (the kernel only allows one
672 component to receive a signal at a time) when you start a signal
673 watcher, and removes it again when you stop it. Perl does the same
674 when you add/remove callbacks to %SIG, so watch out.
675 You can have as many signal watchers per signal as you want.
677 The "signal_ns" variant doesn't start (activate) the newly created
679 watcher.
680 $w->set ($signal)
682 Reconfigures the watcher, see the constructor above for details.
683 Can be called at any time.
684 $current_signum = $w->signal
686 $old_signum = $w->signal ($new_signal)
687 Returns the previously set signal (always as a number not name) and
688 optionally set a new one.
689 CHILD WATCHERS - watch out for process status changes
691 $w = EV::child $pid, $trace, $callback
693 $w = EV::child_ns $pid, $trace, $callback
694 $w = $loop->child ($pid, $trace, $callback)
695 $w = $loop->child_ns ($pid, $trace, $callback)
696 Call the callback when a status change for pid $pid (or any pid if
697 $pid is 0) has been received (a status change happens when the
698 process terminates or is killed, or, when trace is true,
699 additionally when it is stopped or continued). More precisely: when
700 the process receives a "SIGCHLD", EV will fetch the outstanding
701 exit/wait status for all changed/zombie children and call the
702 callback.
703 It is valid (and fully supported) to install a child watcher after
705 a child has exited but before the event loop has started its next
706 iteration (for example, first you "fork", then the new child
707 process might exit, and only then do you install a child watcher in
708 the parent for the new pid).
709 You can access both exit (or tracing) status and pid by using the
711 "rstatus" and "rpid" methods on the watcher object.
712 You can have as many pid watchers per pid as you want, they will
714 all be called.
715 The "child_ns" variant doesn't start (activate) the newly created
717 watcher.
718 $w->set ($pid, $trace)
720 Reconfigures the watcher, see the constructor above for details.
721 Can be called at any time.
722 $current_pid = $w->pid
724 Returns the previously set process id and optionally set a new one.
725 $exit_status = $w->rstatus
727 Return the exit/wait status (as returned by waitpid, see the
728 waitpid entry in perlfunc).
729 $pid = $w->rpid
731 Return the pid of the awaited child (useful when you have installed
732 a watcher for all pids).
733 STAT WATCHERS - did the file attributes just change?
735 $w = EV::stat $path, $interval, $callback
737 $w = EV::stat_ns $path, $interval, $callback
738 $w = $loop->stat ($path, $interval, $callback)
739 $w = $loop->stat_ns ($path, $interval, $callback)
740 Call the callback when a file status change has been detected on
741 $path. The $path does not need to exist, changing from "path
742 exists" to "path does not exist" is a status change like any other.
743 The $interval is a recommended polling interval for systems where
745 OS-supported change notifications don't exist or are not supported.
746 If you use 0 then an unspecified default is used (which is highly
747 recommended!), which is to be expected to be around five seconds
748 usually.
749 This watcher type is not meant for massive numbers of stat
751 watchers, as even with OS-supported change notifications, this can
752 be resource-intensive.
753 The "stat_ns" variant doesn't start (activate) the newly created
755 watcher.
756 ... = $w->stat
758 This call is very similar to the perl "stat" built-in: It stats
759 (using "lstat") the path specified in the watcher and sets perls
760 stat cache (as well as EV's idea of the current stat values) to the
761 values found.
762 In scalar context, a boolean is return indicating success or
764 failure of the stat. In list context, the same 13-value list as
765 with stat is returned (except that the blksize and blocks fields
766 are not reliable).
767 In the case of an error, errno is set to "ENOENT" (regardless of
769 the actual error value) and the "nlink" value is forced to zero (if
770 the stat was successful then nlink is guaranteed to be non-zero).
771 See also the next two entries for more info.
773 ... = $w->attr
775 Just like "$w->stat", but without the initial stat'ing: this
776 returns the values most recently detected by EV. See the next entry
777 for more info.
778 ... = $w->prev
780 Just like "$w->stat", but without the initial stat'ing: this
781 returns the previous set of values, before the change.
782 That is, when the watcher callback is invoked, "$w->prev" will be
784 set to the values found before a change was detected, while
785 "$w->attr" returns the values found leading to the change
786 detection. The difference (if any) between "prev" and "attr" is
787 what triggered the callback.
788 If you did something to the filesystem object and do not want to
790 trigger yet another change, you can call "stat" to update EV's idea
791 of what the current attributes are.
792 $w->set ($path, $interval)
794 Reconfigures the watcher, see the constructor above for details.
795 Can be called at any time.
796 $current_path = $w->path
798 $old_path = $w->path ($new_path)
799 Returns the previously set path and optionally set a new one.
800 $current_interval = $w->interval
802 $old_interval = $w->interval ($new_interval)
803 Returns the previously set interval and optionally set a new one.
804 Can be used to query the actual interval used.
805 IDLE WATCHERS - when you've got nothing better to do...
807 $w = EV::idle $callback
809 $w = EV::idle_ns $callback
810 $w = $loop->idle ($callback)
811 $w = $loop->idle_ns ($callback)
812 Call the callback when there are no other pending watchers of the
813 same or higher priority (excluding check, prepare and other idle
814 watchers of the same or lower priority, of course). They are called
815 idle watchers because when the watcher is the highest priority
816 pending event in the process, the process is considered to be idle
817 at that priority.
818 If you want a watcher that is only ever called when no other events
820 are outstanding you have to set the priority to "EV::MINPRI".
821 The process will not block as long as any idle watchers are active,
823 and they will be called repeatedly until stopped.
824 For example, if you have idle watchers at priority 0 and 1, and an
826 I/O watcher at priority 0, then the idle watcher at priority 1 and
827 the I/O watcher will always run when ready. Only when the idle
828 watcher at priority 1 is stopped and the I/O watcher at priority 0
829 is not pending with the 0-priority idle watcher be invoked.
830 The "idle_ns" variant doesn't start (activate) the newly created
832 watcher.
833 PREPARE WATCHERS - customise your event loop!
835 $w = EV::prepare $callback
837 $w = EV::prepare_ns $callback
838 $w = $loop->prepare ($callback)
839 $w = $loop->prepare_ns ($callback)
840 Call the callback just before the process would block. You can
841 still create/modify any watchers at this point.
842 See the EV::check watcher, below, for explanations and an example.
844 The "prepare_ns" variant doesn't start (activate) the newly created
846 watcher.
847 CHECK WATCHERS - customise your event loop even more!
849 $w = EV::check $callback
851 $w = EV::check_ns $callback
852 $w = $loop->check ($callback)
853 $w = $loop->check_ns ($callback)
854 Call the callback just after the process wakes up again (after it
855 has gathered events), but before any other callbacks have been
856 invoked.
857 This can be used to integrate other event-based software into the
859 EV mainloop: You register a prepare callback and in there, you
860 create io and timer watchers as required by the other software.
861 Here is a real-world example of integrating Net::SNMP (with some
862 details left out):
863 our @snmp_watcher;
865 our $snmp_prepare = EV::prepare sub {
867 # do nothing unless active
868 $dispatcher->{_event_queue_h}
869 or return;
870 # make the dispatcher handle any outstanding stuff
872 ... not shown
873 # create an I/O watcher for each and every socket
875 @snmp_watcher = (
876 (map { EV::io $_, EV::READ, sub { } }
877 keys %{ $dispatcher->{_descriptors} }),
878 EV::timer +($event->[Net::SNMP::Dispatcher::_ACTIVE]
880 ? $event->[Net::SNMP::Dispatcher::_TIME] - EV::now : 0),
881 0, sub { },
882 );
883 };
884 The callbacks are irrelevant (and are not even being called), the
886 only purpose of those watchers is to wake up the process as soon as
887 one of those events occurs (socket readable, or timer timed out).
888 The corresponding EV::check watcher will then clean up:
889 our $snmp_check = EV::check sub {
891 # destroy all watchers
892 @snmp_watcher = ();
893 # make the dispatcher handle any new stuff
895 ... not shown
896 };
897 The callbacks of the created watchers will not be called as the
899 watchers are destroyed before this can happen (remember EV::check
900 gets called first).
901 The "check_ns" variant doesn't start (activate) the newly created
903 watcher.
904 EV::CHECK constant issues
906 Like all other watcher types, there is a bitmask constant for use
907 in $revents and other places. The "EV::CHECK" is special as it has
908 the same name as the "CHECK" sub called by Perl. This doesn't cause
909 big issues on newer perls (beginning with 5.8.9), but it means
910 thatthe constant must be inlined, i.e. runtime calls will not work.
911 That means that as long as you always "use EV" and then "EV::CHECK"
912 you are on the safe side.
913 FORK WATCHERS - the audacity to resume the event loop after a fork
915 Fork watchers are called when a "fork ()" was detected. The invocation
917 is done before the event loop blocks next and before "check" watchers
918 are being called, and only in the child after the fork.
919 $w = EV::fork $callback
921 $w = EV::fork_ns $callback
922 $w = $loop->fork ($callback)
923 $w = $loop->fork_ns ($callback)
924 Call the callback before the event loop is resumed in the child
925 process after a fork.
926 The "fork_ns" variant doesn't start (activate) the newly created
928 watcher.
929 EMBED WATCHERS - when one backend isn't enough...
931 This is a rather advanced watcher type that lets you embed one event
933 loop into another (currently only IO events are supported in the
934 embedded loop, other types of watchers might be handled in a delayed or
935 incorrect fashion and must not be used).
936 See the libev documentation at
938 <http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_embed_code_when_one_backend_>
939 (locally installed as EV::libev) for more details.
940 In short, this watcher is most useful on BSD systems without working
942 kqueue to still be able to handle a large number of sockets:
943 my $socket_loop;
945 # check wether we use SELECT or POLL _and_ KQUEUE is supported
947 if (
948 (EV::backend & (EV::BACKEND_POLL | EV::BACKEND_SELECT))
949 && (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE)
950 ) {
951 # use kqueue for sockets
952 $socket_loop = new EV::Loop EV::BACKEND_KQUEUE | EV::FLAG_NOENV;
953 }
954 # use the default loop otherwise
956 $socket_loop ||= EV::default_loop;
957 $w = EV::embed $otherloop[, $callback]
959 $w = EV::embed_ns $otherloop[, $callback]
960 $w = $loop->embed ($otherloop[, $callback])
961 $w = $loop->embed_ns ($otherloop[, $callback])
962 Call the callback when the embedded event loop ($otherloop) has any
963 I/O activity. The $callback is optional: if it is missing, then the
964 embedded event loop will be managed automatically (which is
965 recommended), otherwise you have to invoke "sweep" yourself.
966 The "embed_ns" variant doesn't start (activate) the newly created
968 watcher.
969 ASYNC WATCHERS - how to wake up another event loop
971 Async watchers are provided by EV, but have little use in perl
973 directly, as perl neither supports threads running in parallel nor
974 direct access to signal handlers or other contexts where they could be
975 of value.
976 It is, however, possible to use them from the XS level.
978 Please see the libev documentation for further details.
980 $w = EV::async $callback
982 $w = EV::async_ns $callback
983 $w = $loop->async ($callback)
984 $w = $loop->async_ns ($callback)
985 $w->send
986 $bool = $w->async_pending
987 CLEANUP WATCHERS - how to clean up when the event loop goes away
989 Cleanup watchers are not supported on the Perl level, they can only be
991 used via XS currently.
992
994 While Perl signal handling (%SIG) is not affected by EV, the behaviour
995 with EV is as the same as any other C library: Perl-signals will only
996 be handled when Perl runs, which means your signal handler might be
997 invoked only the next time an event callback is invoked.
998 The solution is to use EV signal watchers (see "EV::signal"), which
1000 will ensure proper operations with regards to other event watchers.
1001 If you cannot do this for whatever reason, you can also force a watcher
1003 to be called on every event loop iteration by installing a "EV::check"
1004 watcher:
1005 my $async_check = EV::check sub { };
1007 This ensures that perl gets into control for a short time to handle any
1009 pending signals, and also ensures (slightly) slower overall operation.
1010
1012 Ithreads are not supported by this module in any way. Perl pseudo-
1013 threads is evil stuff and must die. Real threads as provided by Coro
1014 are fully supported (and enhanced support is available via Coro::EV).
1015
1017 Most of the "improved" event delivering mechanisms of modern operating
1018 systems have quite a few problems with fork(2) (to put it bluntly: it
1019 is not supported and usually destructive). Libev makes it possible to
1020 work around this by having a function that recreates the kernel state
1021 after fork in the child.
1022 On non-win32 platforms, this module requires the pthread_atfork
1024 functionality to do this automatically for you. This function is quite
1025 buggy on most BSDs, though, so YMMV. The overhead for this is quite
1026 negligible, because everything the function currently does is set a
1027 flag that is checked only when the event loop gets used the next time,
1028 so when you do fork but not use EV, the overhead is minimal.
1029 On win32, there is no notion of fork so all this doesn't apply, of
1031 course.
1032
1034 EV::MakeMaker - MakeMaker interface to XS API, EV::ADNS (asynchronous
1035 DNS), Glib::EV (makes Glib/Gtk2 use EV as event loop), EV::Glib (embed
1036 Glib into EV), Coro::EV (efficient thread integration), Net::SNMP::EV
1037 (asynchronous SNMP), AnyEvent for event-loop agnostic and portable
1038 event driven programming.
1039
1041 Marc Lehmann <schmorp@schmorp.de>
1042 http://home.schmorp.de/
1043perl v5.38.0 2023-07-20 EV(3)