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::loop".
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 flasg 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 returnv alue 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::loop return.
263
264           When called with an argument of EV::BREAK_ALL, all calls to
265           EV::loop 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 a 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 fro 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::loop" 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::loop" 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::loop" (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::loop" from returning just because you happen to have this
439           long-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::loop" 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).
497           If $repeat is non-zero, the timer will be restarted (with the
498           $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       PERIODIC WATCHERS - to cron or not to cron?
546
547       $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
559           It has three distinct "modes":
560
561           ·   absolute timer ($interval = $reschedule_cb = 0)
562
563               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
568           ·   repeating interval timer ($interval > 0, $reschedule_cb = 0)
569
570               In this mode the watcher will always be scheduled to time out
571               at the next "$at + N * $interval" time (for some integer N) and
572               then repeat, regardless of any time jumps.
573
574               This can be used to create timers that do not drift with
575               respect to system time:
576
577                  my $hourly = EV::periodic 0, 3600, 0, sub { print "once/hour\n" };
578
579               That doesn't mean there will always be 3600 seconds in between
580               triggers, but only that the the callback will be called when
581               the system time shows a full hour (UTC).
582
583               Another way to think about it (for the mathematically inclined)
584               is that EV::periodic will try to run the callback in this mode
585               at the next possible time where "$time = $at (mod $interval)",
586               regardless of any time jumps.
587
588           ·   manual reschedule mode ($reschedule_cb = coderef)
589
590               In this mode $interval and $at are both being ignored. Instead,
591               each time the periodic watcher gets scheduled, the reschedule
592               callback ($reschedule_cb) will be called with the watcher as
593               first, and the current time as second argument.
594
595               This callback MUST NOT stop or destroy this or any other
596               periodic watcher, ever, and MUST NOT call any event loop
597               functions or methods. If you need to stop it, return 1e30 and
598               stop it afterwards. You may create and start a "EV::prepare"
599               watcher for this task.
600
601               It must return the next time to trigger, based on the passed
602               time value (that is, the lowest time value larger than or equal
603               to to the second argument). It will usually be called just
604               before the callback will be triggered, but might be called at
605               other times, too.
606
607               This can be used to create very complex timers, such as a timer
608               that triggers on each midnight, local time (actually 24 hours
609               after the last midnight, to keep the example simple. If you
610               know a way to do it correctly in about the same space (without
611               requiring elaborate modules), drop me a note :):
612
613                  my $daily = EV::periodic 0, 0, sub {
614                     my ($w, $now) = @_;
615
616                     use Time::Local ();
617                     my (undef, undef, undef, $d, $m, $y) = localtime $now;
618                     86400 + Time::Local::timelocal 0, 0, 0, $d, $m, $y
619                  }, sub {
620                     print "it's midnight or likely shortly after, now\n";
621                  };
622
623           The "periodic_ns" variant doesn't start (activate) the newly
624           created watcher.
625
626       $w->set ($at, $interval, $reschedule_cb)
627           Reconfigures the watcher, see the constructor above for details.
628           Can be called at any time.
629
630       $w->again
631           Simply stops and starts the watcher again.
632
633       $time = $w->at
634           Return the time that the watcher is expected to trigger next.
635
636       SIGNAL WATCHERS - signal me when a signal gets signalled!
637
638       $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
645           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
649           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
654           You can have as many signal watchers per signal as you want.
655
656           The "signal_ns" variant doesn't start (activate) the newly created
657           watcher.
658
659       $w->set ($signal)
660           Reconfigures the watcher, see the constructor above for details.
661           Can be called at any time.
662
663       $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
668       CHILD WATCHERS - watch out for process status changes
669
670       $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
682           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
688           You can access both exit (or tracing) status and pid by using the
689           "rstatus" and "rpid" methods on the watcher object.
690
691           You can have as many pid watchers per pid as you want, they will
692           all be called.
693
694           The "child_ns" variant doesn't start (activate) the newly created
695           watcher.
696
697       $w->set ($pid, $trace)
698           Reconfigures the watcher, see the constructor above for details.
699           Can be called at any time.
700
701       $current_pid = $w->pid
702           Returns the previously set process id and optionally set a new one.
703
704       $exit_status = $w->rstatus
705           Return the exit/wait status (as returned by waitpid, see the
706           waitpid entry in perlfunc).
707
708       $pid = $w->rpid
709           Return the pid of the awaited child (useful when you have installed
710           a watcher for all pids).
711
712       STAT WATCHERS - did the file attributes just change?
713
714       $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
722           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
728           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
732           The "stat_ns" variant doesn't start (activate) the newly created
733           watcher.
734
735       ... = $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
741           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
746           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
750           See also the next two entries for more info.
751
752       ... = $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
757       ... = $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
761           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
767           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
771       $w->set ($path, $interval)
772           Reconfigures the watcher, see the constructor above for details.
773           Can be called at any time.
774
775       $current_path = $w->path
776       $old_path = $w->path ($new_path)
777           Returns the previously set path and optionally set a new one.
778
779       $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
784       IDLE WATCHERS - when you've got nothing better to do...
785
786       $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
797           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
800           The process will not block as long as any idle watchers are active,
801           and they will be called repeatedly until stopped.
802
803           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
809           The "idle_ns" variant doesn't start (activate) the newly created
810           watcher.
811
812       PREPARE WATCHERS - customise your event loop!
813
814       $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
821           See the EV::check watcher, below, for explanations and an example.
822
823           The "prepare_ns" variant doesn't start (activate) the newly created
824           watcher.
825
826       CHECK WATCHERS - customise your event loop even more!
827
828       $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
836           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
842              our @snmp_watcher;
843
844              our $snmp_prepare = EV::prepare sub {
845                 # do nothing unless active
846                 $dispatcher->{_event_queue_h}
847                    or return;
848
849                 # make the dispatcher handle any outstanding stuff
850                 ... not shown
851
852                 # 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
857                    EV::timer +($event->[Net::SNMP::Dispatcher::_ACTIVE]
858                                ? $event->[Net::SNMP::Dispatcher::_TIME] - EV::now : 0),
859                               0, sub { },
860                 );
861              };
862
863           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
868              our $snmp_check = EV::check sub {
869                 # destroy all watchers
870                 @snmp_watcher = ();
871
872                 # make the dispatcher handle any new stuff
873                 ... not shown
874              };
875
876           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
880           The "check_ns" variant doesn't start (activate) the newly created
881           watcher.
882
883       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
892       FORK WATCHERS - the audacity to resume the event loop after a fork
893
894       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
898       $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
905           The "fork_ns" variant doesn't start (activate) the newly created
906           watcher.
907
908       EMBED WATCHERS - when one backend isn't enough...
909
910       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
915       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
919       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
922          my $socket_loop;
923
924          # 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
933          # use the default loop otherwise
934          $socket_loop ||= EV::default_loop;
935
936       $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
945           The "embed_ns" variant doesn't start (activate) the newly created
946           watcher.
947
948       ASYNC WATCHERS - how to wake up another event loop
949
950       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
955       It is, however, possible to use them from the XS level.
956
957       Please see the libev documentation for further details.
958
959       $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
966       CLEANUP WATCHERS - how to clean up when the event loop goes away
967
968       Cleanup watchers are not supported on the Perl level, they can only be
969       used via XS currently.
970

PERL SIGNALS

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
977       The solution is to use EV signal watchers (see "EV::signal"), which
978       will ensure proper operations with regards to other event watchers.
979
980       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
984          my $async_check = EV::check sub { };
985
986       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

ITHREADS

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

FORK

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
1001       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
1008       On win32, there is no notion of fork so all this doesn't apply, of
1009       course.
1010

SEE ALSO

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

AUTHOR

1019          Marc Lehmann <schmorp@schmorp.de>
1020          http://home.schmorp.de/
1021
1022
1023
1024perl v5.28.0                      2015-12-20                             EV(3)
Impressum