1EV(3)                 User Contributed Perl Documentation                EV(3)
2
3
4

NAME

6       EV - perl interface to libev, a high performance full-featured event
7       loop
8

SYNOPSIS

10          use EV;
11
12          # TIMERS
13
14          my $w = EV::timer 2, 0, sub {
15             warn "is called after 2s";
16          };
17
18          my $w = EV::timer 2, 2, sub {
19             warn "is called roughly every 2s (repeat = 2)";
20          };
21
22          undef $w; # destroy event watcher again
23
24          my $w = EV::periodic 0, 60, 0, sub {
25             warn "is called every minute, on the minute, exactly";
26          };
27
28          # IO
29
30          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
35          # SIGNALS
36
37          my $w = EV::signal 'QUIT', sub {
38             warn "sigquit received\n";
39          };
40
41          # CHILD/PID STATUS CHANGES
42
43          my $w = EV::child 666, 0, sub {
44             my ($w, $revents) = @_;
45             my $status = $w->rstatus;
46          };
47
48          # 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
54          # 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

BEFORE YOU START USING THIS MODULE

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
64       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

DESCRIPTION

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
78       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
84   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
91       This compatibility layer will be switched off in some future release.
92
93       All changes relevant to Perl are renames of symbols, functions and
94       methods:
95
96         EV::loop          => EV::run
97         EV::LOOP_NONBLOCK => EV::RUN_NOWAIT
98         EV::LOOP_ONESHOT  => EV::RUN_ONCE
99
100         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
105         EV::TIMEOUT       => EV::TIMER
106
107         EV::loop_count    => EV::iteration
108         EV::loop_depth    => EV::depth
109         EV::loop_verify   => EV::verify
110
111       The loop object methods corresponding to the functions above have been
112       similarly renamed.
113
114   MODULE EXPORTS
115       This module does not export any symbols.
116

EVENT LOOPS

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
123       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
130       For specific programs you can create additional event loops
131       dynamically.
132
133       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
140       $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
147           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
150           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
156       $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
162       $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
167       $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

BASIC INTERFACE

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
180           If this callback throws an exception it will be silently ignored.
181
182       $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
190       EV::sleep $seconds
191           Block the process for the given number of (fractional) seconds.
192
193       $time = EV::time
194           Returns the current time in (fractional) seconds since the epoch.
195
196       $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
202       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
208           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
212       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
219           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
227           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
232           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
236           Calling "suspend"/"resume" has the side effect of updating the
237           event loop time (see "now_update").
238
239       $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
244       $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
253           The $flags argument can be one of the following:
254
255              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
259       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
264           When called with an argument of EV::BREAK_ALL, all calls to EV::run
265           will return as fast as possible.
266
267           When called with an argument of EV::BREAK_CANCEL, any pending break
268           will be cancelled.
269
270       $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
275       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
281           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
287           If timeout is "undef" or negative, then there will be no timeout.
288           Otherwise an "EV::timer" with this value will be started.
289
290           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
295           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
299       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
306       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
310       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
315       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
325       $count = EV::pending_count
326       $count = $loop->pending_count
327           Returns the number of currently pending watchers.
328
329       EV::invoke_pending
330       $loop->invoke_pending
331           Invoke all currently pending watchers.
332

WATCHER OBJECTS

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
338          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
343       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
348       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
354       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
359       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
363       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
367   COMMON WATCHER METHODS
368       This section lists methods common to all watchers.
369
370       $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
376       $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
382       $bool = $w->is_active
383           Returns true if the watcher is active, false otherwise.
384
385       $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
390              my $w = EV::timer 60, 0, sub {
391                 warn $_[0]->data;
392              };
393              $w->data ("print me!");
394
395       $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
400       $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
408           The default priority of any newly-created watcher is 0.
409
410           Note that the priority semantics have not yet been fleshed out and
411           are subject to almost certain change.
412
413       $w->invoke ($revents)
414           Call the callback *now* with the given event mask.
415
416       $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
420       $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
425       $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
433           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
441           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
445           The initial value for keepalive is true (enabled), and you can
446           change it any time.
447
448           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
451              my $udp_socket = ...
452              my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
453              $udp_watcher->keepalive (0);
454
455       $loop = $w->loop
456           Return the loop that this watcher is attached to.
457

WATCHER TYPES

459       Each of the following subsections describes a single watcher type.
460
461       I/O WATCHERS - is this file descriptor readable or writable?
462
463       $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
470           The $eventmask can be one or more of these constants ORed together:
471
472             EV::READ     wait until read() wouldn't block anymore
473             EV::WRITE    wait until write() wouldn't block anymore
474
475           The "io_ns" variant doesn't start (activate) the newly created
476           watcher.
477
478       $w->set ($fileno_or_fh, $eventmask)
479           Reconfigures the watcher, see the constructor above for details.
480           Can be called at any time.
481
482       $current_fh = $w->fh
483       $old_fh = $w->fh ($new_fh)
484           Returns the previously set filehandle and optionally set a new one.
485
486       $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
490       TIMER WATCHERS - relative and optionally repeating timeouts
491
492       $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
500           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
507           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
512           The "timer_ns" variant doesn't start (activate) the newly created
513           watcher.
514
515       $w->set ($after, $repeat = 0)
516           Reconfigures the watcher, see the constructor above for details.
517           Can be called at any time.
518
519       $w->again
520       $w->again ($repeat)
521           Similar to the "start" method, but has special semantics for
522           repeating timers:
523
524           If the timer is active and non-repeating, it will be stopped.
525
526           If the timer is active and repeating, reset the timeout to occur
527           $repeat seconds after now.
528
529           If the timer is inactive and repeating, start it using the repeat
530           value.
531
532           Otherwise do nothing.
533
534           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
539           If called with a $repeat argument, then it uses this a timer repeat
540           value.
541
542       $after = $w->remaining
543           Calculates and returns the remaining time till the timer will fire.
544
545       $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
552       PERIODIC WATCHERS - to cron or not to cron?
553
554       $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
566           It has three distinct "modes":
567
568           •   absolute timer ($interval = $reschedule_cb = 0)
569
570               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
575           •   repeating interval timer ($interval > 0, $reschedule_cb = 0)
576
577               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
583               This can be used to create timers that do not drift with
584               respect to system time:
585
586                  my $hourly = EV::periodic 0, 3600, 0, sub { print "once/hour\n" };
587
588               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
592               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
597           •   manual reschedule mode ($reschedule_cb = coderef)
598
599               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
604               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
610               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
616               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
620                  my $daily = EV::periodic 0, 0, sub {
621                     my ($w, $now) = @_;
622
623                     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
630           The "periodic_ns" variant doesn't start (activate) the newly
631           created watcher.
632
633       $w->set ($at, $interval, $reschedule_cb)
634           Reconfigures the watcher, see the constructor above for details.
635           Can be called at any time.
636
637       $w->again
638           Simply stops and starts the watcher again.
639
640       $time = $w->at
641           Return the time that the watcher is expected to trigger next.
642
643       $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
650       $interval = $w->interval
651       $old_interval = $w->interval ($new_interval)
652           See above, for the interval attribute.
653
654       $reschedule_cb = $w->reschedule_cb
655       $old_reschedule_cb = $w->reschedule_cb ($new_reschedule_cb)
656           See above, for the reschedule callback.
657
658       SIGNAL WATCHERS - signal me when a signal gets signalled!
659
660       $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
667           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
671           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
676           You can have as many signal watchers per signal as you want.
677
678           The "signal_ns" variant doesn't start (activate) the newly created
679           watcher.
680
681       $w->set ($signal)
682           Reconfigures the watcher, see the constructor above for details.
683           Can be called at any time.
684
685       $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
690       CHILD WATCHERS - watch out for process status changes
691
692       $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
704           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
710           You can access both exit (or tracing) status and pid by using the
711           "rstatus" and "rpid" methods on the watcher object.
712
713           You can have as many pid watchers per pid as you want, they will
714           all be called.
715
716           The "child_ns" variant doesn't start (activate) the newly created
717           watcher.
718
719       $w->set ($pid, $trace)
720           Reconfigures the watcher, see the constructor above for details.
721           Can be called at any time.
722
723       $current_pid = $w->pid
724           Returns the previously set process id and optionally set a new one.
725
726       $exit_status = $w->rstatus
727           Return the exit/wait status (as returned by waitpid, see the
728           waitpid entry in perlfunc).
729
730       $pid = $w->rpid
731           Return the pid of the awaited child (useful when you have installed
732           a watcher for all pids).
733
734       STAT WATCHERS - did the file attributes just change?
735
736       $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
744           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
750           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
754           The "stat_ns" variant doesn't start (activate) the newly created
755           watcher.
756
757       ... = $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
763           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
768           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
772           See also the next two entries for more info.
773
774       ... = $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
779       ... = $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
783           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
789           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
793       $w->set ($path, $interval)
794           Reconfigures the watcher, see the constructor above for details.
795           Can be called at any time.
796
797       $current_path = $w->path
798       $old_path = $w->path ($new_path)
799           Returns the previously set path and optionally set a new one.
800
801       $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
806       IDLE WATCHERS - when you've got nothing better to do...
807
808       $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
819           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
822           The process will not block as long as any idle watchers are active,
823           and they will be called repeatedly until stopped.
824
825           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
831           The "idle_ns" variant doesn't start (activate) the newly created
832           watcher.
833
834       PREPARE WATCHERS - customise your event loop!
835
836       $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
843           See the EV::check watcher, below, for explanations and an example.
844
845           The "prepare_ns" variant doesn't start (activate) the newly created
846           watcher.
847
848       CHECK WATCHERS - customise your event loop even more!
849
850       $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
858           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
864              our @snmp_watcher;
865
866              our $snmp_prepare = EV::prepare sub {
867                 # do nothing unless active
868                 $dispatcher->{_event_queue_h}
869                    or return;
870
871                 # make the dispatcher handle any outstanding stuff
872                 ... not shown
873
874                 # 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
879                    EV::timer +($event->[Net::SNMP::Dispatcher::_ACTIVE]
880                                ? $event->[Net::SNMP::Dispatcher::_TIME] - EV::now : 0),
881                               0, sub { },
882                 );
883              };
884
885           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
890              our $snmp_check = EV::check sub {
891                 # destroy all watchers
892                 @snmp_watcher = ();
893
894                 # make the dispatcher handle any new stuff
895                 ... not shown
896              };
897
898           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
902           The "check_ns" variant doesn't start (activate) the newly created
903           watcher.
904
905       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
914       FORK WATCHERS - the audacity to resume the event loop after a fork
915
916       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
920       $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
927           The "fork_ns" variant doesn't start (activate) the newly created
928           watcher.
929
930       EMBED WATCHERS - when one backend isn't enough...
931
932       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
937       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
941       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
944          my $socket_loop;
945
946          # 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
955          # use the default loop otherwise
956          $socket_loop ||= EV::default_loop;
957
958       $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
967           The "embed_ns" variant doesn't start (activate) the newly created
968           watcher.
969
970       ASYNC WATCHERS - how to wake up another event loop
971
972       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
977       It is, however, possible to use them from the XS level.
978
979       Please see the libev documentation for further details.
980
981       $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
988       CLEANUP WATCHERS - how to clean up when the event loop goes away
989
990       Cleanup watchers are not supported on the Perl level, they can only be
991       used via XS currently.
992

PERL SIGNALS

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
999       The solution is to use EV signal watchers (see "EV::signal"), which
1000       will ensure proper operations with regards to other event watchers.
1001
1002       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
1006          my $async_check = EV::check sub { };
1007
1008       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

ITHREADS

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

FORK

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
1023       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
1030       On win32, there is no notion of fork so all this doesn't apply, of
1031       course.
1032

SEE ALSO

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

AUTHOR

1041          Marc Lehmann <schmorp@schmorp.de>
1042          http://home.schmorp.de/
1043
1044
1045
1046perl v5.34.0                      2021-07-22                             EV(3)
Impressum