File Coverage

blib/lib/EV.pm
Criterion Covered Total %
statement 9 9 100.0
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 12 12 100.0


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             EV - perl interface to libev, a high performance full-featured event loop
4              
5             =head1 SYNOPSIS
6              
7             use EV;
8            
9             # TIMERS
10            
11             my $w = EV::timer 2, 0, sub {
12             warn "is called after 2s";
13             };
14            
15             my $w = EV::timer 2, 2, sub {
16             warn "is called roughly every 2s (repeat = 2)";
17             };
18            
19             undef $w; # destroy event watcher again
20            
21             my $w = EV::periodic 0, 60, 0, sub {
22             warn "is called every minute, on the minute, exactly";
23             };
24            
25             # IO
26            
27             my $w = EV::io *STDIN, EV::READ, sub {
28             my ($w, $revents) = @_; # all callbacks receive the watcher and event mask
29             warn "stdin is readable, you entered: ", ;
30             };
31            
32             # SIGNALS
33            
34             my $w = EV::signal 'QUIT', sub {
35             warn "sigquit received\n";
36             };
37            
38             # CHILD/PID STATUS CHANGES
39            
40             my $w = EV::child 666, 0, sub {
41             my ($w, $revents) = @_;
42             my $status = $w->rstatus;
43             };
44            
45             # STAT CHANGES
46             my $w = EV::stat "/etc/passwd", 10, sub {
47             my ($w, $revents) = @_;
48             warn $w->path, " has changed somehow.\n";
49             };
50            
51             # MAINLOOP
52             EV::run; # loop until EV::break is called or all watchers stop
53             EV::run EV::RUN_ONCE; # block until at least one event could be handled
54             EV::run EV::RUN_NOWAIT; # try to handle same events, but do not block
55              
56             =head1 BEFORE YOU START USING THIS MODULE
57              
58             If you only need timer, I/O, signal, child and idle watchers and not the
59             advanced functionality of this module, consider using L instead,
60             specifically the simplified API described in L.
61              
62             When used with EV as backend, the L API is as fast as the native L
63             API, but your programs/modules will still run with many other event loops.
64              
65             =head1 DESCRIPTION
66              
67             This module provides an interface to libev
68             (L). While the documentation
69             below is comprehensive, one might also consult the documentation of
70             libev itself (L or
71             F) for more subtle details on watcher semantics or some
72             discussion on the available backends, or how to force a specific backend
73             with C, or just about in any case because it has much more
74             detailed information.
75              
76             This module is very fast and scalable. It is actually so fast that you
77             can use it through the L module, stay portable to other event
78             loops (if you don't rely on any watcher types not available through it)
79             and still be faster than with any other event loop currently supported in
80             Perl.
81              
82             =head2 PORTING FROM EV 3.X to 4.X
83              
84             EV version 4 introduces a number of incompatible changes summarised
85             here. According to the depreciation strategy used by libev, there is a
86             compatibility layer in place so programs should continue to run unchanged
87             (the XS interface lacks this layer, so programs using that one need to be
88             updated).
89              
90             This compatibility layer will be switched off in some future release.
91              
92             All changes relevant to Perl are renames of symbols, functions and
93             methods:
94              
95             EV::loop => EV::run
96             EV::LOOP_NONBLOCK => EV::RUN_NOWAIT
97             EV::LOOP_ONESHOT => EV::RUN_ONCE
98              
99             EV::unloop => EV::break
100             EV::UNLOOP_CANCEL => EV::BREAK_CANCEL
101             EV::UNLOOP_ONE => EV::BREAK_ONE
102             EV::UNLOOP_ALL => EV::BREAK_ALL
103              
104             EV::TIMEOUT => EV::TIMER
105              
106             EV::loop_count => EV::iteration
107             EV::loop_depth => EV::depth
108             EV::loop_verify => EV::verify
109              
110             The loop object methods corresponding to the functions above have been
111             similarly renamed.
112              
113             =head2 MODULE EXPORTS
114              
115             This module does not export any symbols.
116              
117             =cut
118              
119             package EV;
120              
121 5     5   29305 use common::sense;
  5         92  
  5         25  
122              
123             BEGIN {
124 5     5   16 our $VERSION = '4.32';
125 5     5   461 use XSLoader;
  5         8  
  5         205  
126 5         23 local $^W = 0; # avoid spurious warning
127 5         8599 XSLoader::load "EV", $VERSION;
128             }
129              
130             @EV::IO::ISA =
131             @EV::Timer::ISA =
132             @EV::Periodic::ISA =
133             @EV::Signal::ISA =
134             @EV::Child::ISA =
135             @EV::Stat::ISA =
136             @EV::Idle::ISA =
137             @EV::Prepare::ISA =
138             @EV::Check::ISA =
139             @EV::Embed::ISA =
140             @EV::Fork::ISA =
141             @EV::Async::ISA =
142             "EV::Watcher";
143              
144             @EV::Loop::Default::ISA = "EV::Loop";
145              
146             =head1 EVENT LOOPS
147              
148             EV supports multiple event loops: There is a single "default event loop"
149             that can handle everything including signals and child watchers, and any
150             number of "dynamic event loops" that can use different backends (with
151             various limitations), but no child and signal watchers.
152              
153             You do not have to do anything to create the default event loop: When
154             the module is loaded a suitable backend is selected on the premise of
155             selecting a working backend (which for example rules out kqueue on most
156             BSDs). Modules should, unless they have "special needs" always use the
157             default loop as this is fastest (perl-wise), best supported by other
158             modules (e.g. AnyEvent or Coro) and most portable event loop.
159              
160             For specific programs you can create additional event loops dynamically.
161              
162             If you want to take advantage of kqueue (which often works properly for
163             sockets only) even though the default loop doesn't enable it, you can
164             I a kqueue loop into the default loop: running the default loop
165             will then also service the kqueue loop to some extent. See the example in
166             the section about embed watchers for an example on how to achieve that.
167              
168             =over 4
169              
170             =item $loop = new EV::Loop [$flags]
171              
172             Create a new event loop as per the specified flags. Please refer to
173             the C function description in the libev documentation
174             (L,
175             or locally-installed as F manpage) for more info.
176              
177             The loop will automatically be destroyed when it is no longer referenced
178             by any watcher and the loop object goes out of scope.
179              
180             If you are not embedding the loop, then Using C
181             is recommended, as only the default event loop is protected by this
182             module. If you I embedding this loop in the default loop, this is not
183             necessary, as C automatically does the right thing on fork.
184              
185             =item $loop->loop_fork
186              
187             Must be called after a fork in the child, before entering or continuing
188             the event loop. An alternative is to use C which calls
189             this function automatically, at some performance loss (refer to the libev
190             documentation).
191              
192             =item $loop->verify
193              
194             Calls C to make internal consistency checks (for debugging
195             libev) and abort the program if any data structures were found to be
196             corrupted.
197              
198             =item $loop = EV::default_loop [$flags]
199              
200             Return the default loop (which is a singleton object). Since this module
201             already creates the default loop with default flags, specifying flags here
202             will not have any effect unless you destroy the default loop first, which
203             isn't supported. So in short: don't do it, and if you break it, you get to
204             keep the pieces.
205              
206             =back
207              
208              
209             =head1 BASIC INTERFACE
210              
211             =over 4
212              
213             =item $EV::DIED
214              
215             Must contain a reference to a function that is called when a callback
216             throws an exception (with $@ containing the error). The default prints an
217             informative message and continues.
218              
219             If this callback throws an exception it will be silently ignored.
220              
221             =item $flags = EV::supported_backends
222              
223             =item $flags = EV::recommended_backends
224              
225             =item $flags = EV::embeddable_backends
226              
227             Returns the set (see C flags) of backends supported by this
228             instance of EV, the set of recommended backends (supposed to be good) for
229             this platform and the set of embeddable backends (see EMBED WATCHERS).
230              
231             =item EV::sleep $seconds
232              
233             Block the process for the given number of (fractional) seconds.
234              
235             =item $time = EV::time
236              
237             Returns the current time in (fractional) seconds since the epoch.
238              
239             =item $time = EV::now
240              
241             =item $time = $loop->now
242              
243             Returns the time the last event loop iteration has been started. This
244             is the time that (relative) timers are based on, and referring to it is
245             usually faster then calling EV::time.
246              
247             =item EV::now_update
248              
249             =item $loop->now_update
250              
251             Establishes the current time by querying the kernel, updating the time
252             returned by C in the progress. This is a costly operation and
253             is usually done automatically within C.
254              
255             This function is rarely useful, but when some event callback runs for a
256             very long time without entering the event loop, updating libev's idea of
257             the current time is a good idea.
258              
259             =item EV::suspend
260              
261             =item $loop->suspend
262              
263             =item EV::resume
264              
265             =item $loop->resume
266              
267             These two functions suspend and resume a loop, for use when the loop is
268             not used for a while and timeouts should not be processed.
269              
270             A typical use case would be an interactive program such as a game: When
271             the user presses C<^Z> to suspend the game and resumes it an hour later it
272             would be best to handle timeouts as if no time had actually passed while
273             the program was suspended. This can be achieved by calling C
274             in your C handler, sending yourself a C and calling
275             C directly afterwards to resume timer processing.
276              
277             Effectively, all C watchers will be delayed by the time spend
278             between C and C, and all C watchers
279             will be rescheduled (that is, they will lose any events that would have
280             occured while suspended).
281              
282             After calling C you B call I function on the given
283             loop other than C, and you B call C
284             without a previous call to C.
285              
286             Calling C/C has the side effect of updating the event
287             loop time (see C).
288              
289             =item $backend = EV::backend
290              
291             =item $backend = $loop->backend
292              
293             Returns an integer describing the backend used by libev (EV::BACKEND_SELECT
294             or EV::BACKEND_EPOLL).
295              
296             =item $active = EV::run [$flags]
297              
298             =item $active = $loop->run ([$flags])
299              
300             Begin checking for events and calling callbacks. It returns when a
301             callback calls EV::break or the flags are nonzero (in which case the
302             return value is true) or when there are no active watchers which reference
303             the loop (keepalive is true), in which case the return value will be
304             false. The return value can generally be interpreted as "if true, there is
305             more work left to do".
306              
307             The $flags argument can be one of the following:
308              
309             0 as above
310             EV::RUN_ONCE block at most once (wait, but do not loop)
311             EV::RUN_NOWAIT do not block at all (fetch/handle events but do not wait)
312              
313             =item EV::break [$how]
314              
315             =item $loop->break ([$how])
316              
317             When called with no arguments or an argument of EV::BREAK_ONE, makes the
318             innermost call to EV::run return.
319              
320             When called with an argument of EV::BREAK_ALL, all calls to EV::run will
321             return as fast as possible.
322              
323             When called with an argument of EV::BREAK_CANCEL, any pending break will
324             be cancelled.
325              
326             =item $count = EV::iteration
327              
328             =item $count = $loop->iteration
329              
330             Return the number of times the event loop has polled for new
331             events. Sometimes useful as a generation counter.
332              
333             =item EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
334              
335             =item $loop->once ($fh_or_undef, $events, $timeout, $cb->($revents))
336              
337             This function rolls together an I/O and a timer watcher for a single
338             one-shot event without the need for managing a watcher object.
339              
340             If C<$fh_or_undef> is a filehandle or file descriptor, then C<$events>
341             must be a bitset containing either C, C or C
342             | EV::WRITE>, indicating the type of I/O event you want to wait for. If
343             you do not want to wait for some I/O event, specify C for
344             C<$fh_or_undef> and C<0> for C<$events>).
345              
346             If timeout is C or negative, then there will be no
347             timeout. Otherwise an C with this value will be started.
348              
349             When an error occurs or either the timeout or I/O watcher triggers, then
350             the callback will be called with the received event set (in general
351             you can expect it to be a combination of C, C,
352             C and C).
353              
354             EV::once doesn't return anything: the watchers stay active till either
355             of them triggers, then they will be stopped and freed, and the callback
356             invoked.
357              
358             =item EV::feed_fd_event $fd, $revents
359              
360             =item $loop->feed_fd_event ($fd, $revents)
361              
362             Feed an event on a file descriptor into EV. EV will react to this call as
363             if the readyness notifications specified by C<$revents> (a combination of
364             C and C) happened on the file descriptor C<$fd>.
365              
366             =item EV::feed_signal_event $signal
367              
368             Feed a signal event into the default loop. EV will react to this call as
369             if the signal specified by C<$signal> had occured.
370              
371             =item EV::feed_signal $signal
372              
373             Feed a signal event into EV - unlike C, this works
374             regardless of which loop has registered the signal, and is mainly useful
375             for custom signal implementations.
376              
377             =item EV::set_io_collect_interval $time
378              
379             =item $loop->set_io_collect_interval ($time)
380              
381             =item EV::set_timeout_collect_interval $time
382              
383             =item $loop->set_timeout_collect_interval ($time)
384              
385             These advanced functions set the minimum block interval when polling for I/O events and the minimum
386             wait interval for timer events. See the libev documentation at
387             L
388             (locally installed as F) for a more detailed discussion.
389              
390             =item $count = EV::pending_count
391              
392             =item $count = $loop->pending_count
393              
394             Returns the number of currently pending watchers.
395              
396             =item EV::invoke_pending
397              
398             =item $loop->invoke_pending
399              
400             Invoke all currently pending watchers.
401              
402             =back
403              
404              
405             =head1 WATCHER OBJECTS
406              
407             A watcher is an object that gets created to record your interest in some
408             event. For instance, if you want to wait for STDIN to become readable, you
409             would create an EV::io watcher for that:
410              
411             my $watcher = EV::io *STDIN, EV::READ, sub {
412             my ($watcher, $revents) = @_;
413             warn "yeah, STDIN should now be readable without blocking!\n"
414             };
415              
416             All watchers can be active (waiting for events) or inactive (paused). Only
417             active watchers will have their callbacks invoked. All callbacks will be
418             called with at least two arguments: the watcher and a bitmask of received
419             events.
420              
421             Each watcher type has its associated bit in revents, so you can use the
422             same callback for multiple watchers. The event mask is named after the
423             type, i.e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
424             EV::periodic sets EV::PERIODIC and so on, with the exception of I/O events
425             (which can set both EV::READ and EV::WRITE bits).
426              
427             In the rare case where one wants to create a watcher but not start it at
428             the same time, each constructor has a variant with a trailing C<_ns> in
429             its name, e.g. EV::io has a non-starting variant EV::io_ns and so on.
430              
431             Please note that a watcher will automatically be stopped when the watcher
432             object is destroyed, so you I to keep the watcher objects returned by
433             the constructors.
434              
435             Also, all methods changing some aspect of a watcher (->set, ->priority,
436             ->fh and so on) automatically stop and start it again if it is active,
437             which means pending events get lost.
438              
439             =head2 COMMON WATCHER METHODS
440              
441             This section lists methods common to all watchers.
442              
443             =over 4
444              
445             =item $w->start
446              
447             Starts a watcher if it isn't active already. Does nothing to an already
448             active watcher. By default, all watchers start out in the active state
449             (see the description of the C<_ns> variants if you need stopped watchers).
450              
451             =item $w->stop
452              
453             Stop a watcher if it is active. Also clear any pending events (events that
454             have been received but that didn't yet result in a callback invocation),
455             regardless of whether the watcher was active or not.
456              
457             =item $bool = $w->is_active
458              
459             Returns true if the watcher is active, false otherwise.
460              
461             =item $current_data = $w->data
462              
463             =item $old_data = $w->data ($new_data)
464              
465             Queries a freely usable data scalar on the watcher and optionally changes
466             it. This is a way to associate custom data with a watcher:
467              
468             my $w = EV::timer 60, 0, sub {
469             warn $_[0]->data;
470             };
471             $w->data ("print me!");
472              
473             =item $current_cb = $w->cb
474              
475             =item $old_cb = $w->cb ($new_cb)
476              
477             Queries the callback on the watcher and optionally changes it. You can do
478             this at any time without the watcher restarting.
479              
480             =item $current_priority = $w->priority
481              
482             =item $old_priority = $w->priority ($new_priority)
483              
484             Queries the priority on the watcher and optionally changes it. Pending
485             watchers with higher priority will be invoked first. The valid range of
486             priorities lies between EV::MAXPRI (default 2) and EV::MINPRI (default
487             -2). If the priority is outside this range it will automatically be
488             normalised to the nearest valid priority.
489              
490             The default priority of any newly-created watcher is 0.
491              
492             Note that the priority semantics have not yet been fleshed out and are
493             subject to almost certain change.
494              
495             =item $w->invoke ($revents)
496              
497             Call the callback *now* with the given event mask.
498              
499             =item $w->feed_event ($revents)
500              
501             Feed some events on this watcher into EV. EV will react to this call as if
502             the watcher had received the given C<$revents> mask.
503              
504             =item $revents = $w->clear_pending
505              
506             If the watcher is pending, this function clears its pending status and
507             returns its C<$revents> bitset (as if its callback was invoked). If the
508             watcher isn't pending it does nothing and returns C<0>.
509              
510             =item $previous_state = $w->keepalive ($bool)
511              
512             Normally, C will return when there are no active watchers
513             (which is a "deadlock" because no progress can be made anymore). This is
514             convenient because it allows you to start your watchers (and your jobs),
515             call C once and when it returns you know that all your jobs are
516             finished (or they forgot to register some watchers for their task :).
517              
518             Sometimes, however, this gets in your way, for example when the module
519             that calls C (usually the main program) is not the same module
520             as a long-living watcher (for example a DNS client module written by
521             somebody else even). Then you might want any outstanding requests to be
522             handled, but you would not want to keep C from returning just
523             because you happen to have this long-running UDP port watcher.
524              
525             In this case you can clear the keepalive status, which means that even
526             though your watcher is active, it won't keep C from returning.
527              
528             The initial value for keepalive is true (enabled), and you can change it
529             any time.
530              
531             Example: Register an I/O watcher for some UDP socket but do not keep the
532             event loop from running just because of that watcher.
533              
534             my $udp_socket = ...
535             my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
536             $udp_watcher->keepalive (0);
537              
538             =item $loop = $w->loop
539              
540             Return the loop that this watcher is attached to.
541              
542             =back
543              
544              
545             =head1 WATCHER TYPES
546              
547             Each of the following subsections describes a single watcher type.
548              
549             =head3 I/O WATCHERS - is this file descriptor readable or writable?
550              
551             =over 4
552              
553             =item $w = EV::io $fileno_or_fh, $eventmask, $callback
554              
555             =item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
556              
557             =item $w = $loop->io ($fileno_or_fh, $eventmask, $callback)
558              
559             =item $w = $loop->io_ns ($fileno_or_fh, $eventmask, $callback)
560              
561             As long as the returned watcher object is alive, call the C<$callback>
562             when at least one of events specified in C<$eventmask> occurs.
563              
564             The $eventmask can be one or more of these constants ORed together:
565              
566             EV::READ wait until read() wouldn't block anymore
567             EV::WRITE wait until write() wouldn't block anymore
568              
569             The C variant doesn't start (activate) the newly created watcher.
570              
571             =item $w->set ($fileno_or_fh, $eventmask)
572              
573             Reconfigures the watcher, see the constructor above for details. Can be
574             called at any time.
575              
576             =item $current_fh = $w->fh
577              
578             =item $old_fh = $w->fh ($new_fh)
579              
580             Returns the previously set filehandle and optionally set a new one.
581              
582             =item $current_eventmask = $w->events
583              
584             =item $old_eventmask = $w->events ($new_eventmask)
585              
586             Returns the previously set event mask and optionally set a new one.
587              
588             =back
589              
590              
591             =head3 TIMER WATCHERS - relative and optionally repeating timeouts
592              
593             =over 4
594              
595             =item $w = EV::timer $after, $repeat, $callback
596              
597             =item $w = EV::timer_ns $after, $repeat, $callback
598              
599             =item $w = $loop->timer ($after, $repeat, $callback)
600              
601             =item $w = $loop->timer_ns ($after, $repeat, $callback)
602              
603             Calls the callback after C<$after> seconds (which may be fractional or
604             negative). If C<$repeat> is non-zero, the timer will be restarted (with
605             the $repeat value as $after) after the callback returns.
606              
607             This means that the callback would be called roughly after C<$after>
608             seconds, and then every C<$repeat> seconds. The timer does his best not
609             to drift, but it will not invoke the timer more often then once per event
610             loop iteration, and might drift in other cases. If that isn't acceptable,
611             look at EV::periodic, which can provide long-term stable timers.
612              
613             The timer is based on a monotonic clock, that is, if somebody is sitting
614             in front of the machine while the timer is running and changes the system
615             clock, the timer will nevertheless run (roughly) the same time.
616              
617             The C variant doesn't start (activate) the newly created watcher.
618              
619             =item $w->set ($after, $repeat = 0)
620              
621             Reconfigures the watcher, see the constructor above for details. Can be called at
622             any time.
623              
624             =item $w->again
625              
626             =item $w->again ($repeat)
627              
628             Similar to the C method, but has special semantics for repeating timers:
629              
630             If the timer is active and non-repeating, it will be stopped.
631              
632             If the timer is active and repeating, reset the timeout to occur
633             C<$repeat> seconds after now.
634              
635             If the timer is inactive and repeating, start it using the repeat value.
636              
637             Otherwise do nothing.
638              
639             This behaviour is useful when you have a timeout for some IO
640             operation. You create a timer object with the same value for C<$after> and
641             C<$repeat>, and then, in the read/write watcher, run the C method
642             on the timeout.
643              
644             If called with a C<$repeat> argument, then it uses this a timer repeat
645             value.
646              
647             =item $after = $w->remaining
648              
649             Calculates and returns the remaining time till the timer will fire.
650              
651             =item $repeat = $w->repeat
652              
653             =item $old_repeat = $w->repeat ($new_repeat)
654              
655             Returns the current value of the repeat attribute and optionally sets a
656             new one. Setting the new one will not restart the watcher - if the watcher
657             is active, the new repeat value is used whenever it expires next.
658              
659             =back
660              
661              
662             =head3 PERIODIC WATCHERS - to cron or not to cron?
663              
664             =over 4
665              
666             =item $w = EV::periodic $at, $interval, $reschedule_cb, $callback
667              
668             =item $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
669              
670             =item $w = $loop->periodic ($at, $interval, $reschedule_cb, $callback)
671              
672             =item $w = $loop->periodic_ns ($at, $interval, $reschedule_cb, $callback)
673              
674             Similar to EV::timer, but is not based on relative timeouts but on
675             absolute times. Apart from creating "simple" timers that trigger "at" the
676             specified time, it can also be used for non-drifting absolute timers and
677             more complex, cron-like, setups that are not adversely affected by time
678             jumps (i.e. when the system clock is changed by explicit date -s or other
679             means such as ntpd). It is also the most complex watcher type in EV.
680              
681             It has three distinct "modes":
682              
683             =over 4
684              
685             =item * absolute timer ($interval = $reschedule_cb = 0)
686              
687             This time simply fires at the wallclock time C<$at> and doesn't repeat. It
688             will not adjust when a time jump occurs, that is, if it is to be run
689             at January 1st 2011 then it will run when the system time reaches or
690             surpasses this time.
691              
692             =item * repeating interval timer ($interval > 0, $reschedule_cb = 0)
693              
694             In this mode the watcher will always be scheduled to time out at the
695             next C<$at + N * $interval> time (for the lowest integer N) and then repeat,
696             regardless of any time jumps. Note that, since C can be negative, the
697             first trigger can happen before C<$at>.
698              
699             This can be used to create timers that do not drift with respect to system
700             time:
701              
702             my $hourly = EV::periodic 0, 3600, 0, sub { print "once/hour\n" };
703              
704             That doesn't mean there will always be 3600 seconds in between triggers,
705             but only that the the callback will be called when the system time shows a
706             full hour (UTC).
707              
708             Another way to think about it (for the mathematically inclined) is that
709             EV::periodic will try to run the callback in this mode at the next
710             possible time where C<$time = $at (mod $interval)>, regardless of any time
711             jumps.
712              
713             =item * manual reschedule mode ($reschedule_cb = coderef)
714              
715             In this mode $interval and $at are both being ignored. Instead, each
716             time the periodic watcher gets scheduled, the reschedule callback
717             ($reschedule_cb) will be called with the watcher as first, and the current
718             time as second argument.
719              
720             I
721             watcher, ever, and MUST NOT call any event loop functions or methods>. If
722             you need to stop it, return 1e30 and stop it afterwards. You may create
723             and start an C watcher for this task.
724              
725             It must return the next time to trigger, based on the passed time value
726             (that is, the lowest time value larger than or equal to to the second
727             argument). It will usually be called just before the callback will be
728             triggered, but might be called at other times, too.
729              
730             This can be used to create very complex timers, such as a timer that
731             triggers on each midnight, local time (actually one day after the last
732             midnight, to keep the example simple):
733              
734             my $daily = EV::periodic 0, 0, sub {
735             my ($w, $now) = @_;
736              
737             use Time::Local ();
738             my (undef, undef, undef, $d, $m, $y) = localtime $now;
739             Time::Local::timelocal_nocheck 0, 0, 0, $d + 1, $m, $y
740             }, sub {
741             print "it's midnight or likely shortly after, now\n";
742             };
743              
744             =back
745              
746             The C variant doesn't start (activate) the newly created watcher.
747              
748             =item $w->set ($at, $interval, $reschedule_cb)
749              
750             Reconfigures the watcher, see the constructor above for details. Can be called at
751             any time.
752              
753             =item $w->again
754              
755             Simply stops and starts the watcher again.
756              
757             =item $time = $w->at
758              
759             Return the time that the watcher is expected to trigger next.
760              
761             =item $offset = $w->offset
762              
763             =item $old_offset = $w->offset ($new_offset)
764              
765             Returns the current value of the offset attribute and optionally sets a
766             new one. Setting the new one will not restart the watcher - if the watcher
767             is active, the new offset value is used whenever it expires next.
768              
769             =item $interval = $w->interval
770              
771             =item $old_interval = $w->interval ($new_interval)
772              
773             See above, for the interval attribute.
774              
775             =item $reschedule_cb = $w->reschedule_cb
776              
777             =item $old_reschedule_cb = $w->reschedule_cb ($new_reschedule_cb)
778              
779             See above, for the reschedule callback.
780              
781             =back
782              
783              
784             =head3 SIGNAL WATCHERS - signal me when a signal gets signalled!
785              
786             =over 4
787              
788             =item $w = EV::signal $signal, $callback
789              
790             =item $w = EV::signal_ns $signal, $callback
791              
792             =item $w = $loop->signal ($signal, $callback)
793              
794             =item $w = $loop->signal_ns ($signal, $callback)
795              
796             Call the callback when $signal is received (the signal can be specified by
797             number or by name, just as with C or C<%SIG>).
798              
799             Only one event loop can grab a given signal - attempting to grab the same
800             signal from two EV loops will crash the program immediately or cause data
801             corruption.
802              
803             EV will grab the signal for the process (the kernel only allows one
804             component to receive a signal at a time) when you start a signal watcher,
805             and removes it again when you stop it. Perl does the same when you
806             add/remove callbacks to C<%SIG>, so watch out.
807              
808             You can have as many signal watchers per signal as you want.
809              
810             The C variant doesn't start (activate) the newly created watcher.
811              
812             =item $w->set ($signal)
813              
814             Reconfigures the watcher, see the constructor above for details. Can be
815             called at any time.
816              
817             =item $current_signum = $w->signal
818              
819             =item $old_signum = $w->signal ($new_signal)
820              
821             Returns the previously set signal (always as a number not name) and
822             optionally set a new one.
823              
824             =back
825              
826              
827             =head3 CHILD WATCHERS - watch out for process status changes
828              
829             =over 4
830              
831             =item $w = EV::child $pid, $trace, $callback
832              
833             =item $w = EV::child_ns $pid, $trace, $callback
834              
835             =item $w = $loop->child ($pid, $trace, $callback)
836              
837             =item $w = $loop->child_ns ($pid, $trace, $callback)
838              
839             Call the callback when a status change for pid C<$pid> (or any pid
840             if C<$pid> is 0) has been received (a status change happens when the
841             process terminates or is killed, or, when trace is true, additionally when
842             it is stopped or continued). More precisely: when the process receives
843             a C, EV will fetch the outstanding exit/wait status for all
844             changed/zombie children and call the callback.
845              
846             It is valid (and fully supported) to install a child watcher after a child
847             has exited but before the event loop has started its next iteration (for
848             example, first you C, then the new child process might exit, and
849             only then do you install a child watcher in the parent for the new pid).
850              
851             You can access both exit (or tracing) status and pid by using the
852             C and C methods on the watcher object.
853              
854             You can have as many pid watchers per pid as you want, they will all be
855             called.
856              
857             The C variant doesn't start (activate) the newly created watcher.
858              
859             =item $w->set ($pid, $trace)
860              
861             Reconfigures the watcher, see the constructor above for details. Can be called at
862             any time.
863              
864             =item $current_pid = $w->pid
865              
866             Returns the previously set process id and optionally set a new one.
867              
868             =item $exit_status = $w->rstatus
869              
870             Return the exit/wait status (as returned by waitpid, see the waitpid entry
871             in perlfunc).
872              
873             =item $pid = $w->rpid
874              
875             Return the pid of the awaited child (useful when you have installed a
876             watcher for all pids).
877              
878             =back
879              
880              
881             =head3 STAT WATCHERS - did the file attributes just change?
882              
883             =over 4
884              
885             =item $w = EV::stat $path, $interval, $callback
886              
887             =item $w = EV::stat_ns $path, $interval, $callback
888              
889             =item $w = $loop->stat ($path, $interval, $callback)
890              
891             =item $w = $loop->stat_ns ($path, $interval, $callback)
892              
893             Call the callback when a file status change has been detected on
894             C<$path>. The C<$path> does not need to exist, changing from "path exists"
895             to "path does not exist" is a status change like any other.
896              
897             The C<$interval> is a recommended polling interval for systems where
898             OS-supported change notifications don't exist or are not supported. If
899             you use C<0> then an unspecified default is used (which is highly
900             recommended!), which is to be expected to be around five seconds usually.
901              
902             This watcher type is not meant for massive numbers of stat watchers,
903             as even with OS-supported change notifications, this can be
904             resource-intensive.
905              
906             The C variant doesn't start (activate) the newly created watcher.
907              
908             =item ... = $w->stat
909              
910             This call is very similar to the perl C built-in: It stats (using
911             C) the path specified in the watcher and sets perls stat cache (as
912             well as EV's idea of the current stat values) to the values found.
913              
914             In scalar context, a boolean is return indicating success or failure of
915             the stat. In list context, the same 13-value list as with stat is returned
916             (except that the blksize and blocks fields are not reliable).
917              
918             In the case of an error, errno is set to C (regardless of the
919             actual error value) and the C value is forced to zero (if the stat
920             was successful then nlink is guaranteed to be non-zero).
921              
922             See also the next two entries for more info.
923              
924             =item ... = $w->attr
925              
926             Just like C<< $w->stat >>, but without the initial stat'ing: this returns
927             the values most recently detected by EV. See the next entry for more info.
928              
929             =item ... = $w->prev
930              
931             Just like C<< $w->stat >>, but without the initial stat'ing: this returns
932             the previous set of values, before the change.
933              
934             That is, when the watcher callback is invoked, C<< $w->prev >> will be set
935             to the values found I a change was detected, while C<< $w->attr >>
936             returns the values found leading to the change detection. The difference (if any)
937             between C and C is what triggered the callback.
938              
939             If you did something to the filesystem object and do not want to trigger
940             yet another change, you can call C to update EV's idea of what the
941             current attributes are.
942              
943             =item $w->set ($path, $interval)
944              
945             Reconfigures the watcher, see the constructor above for details. Can be
946             called at any time.
947              
948             =item $current_path = $w->path
949              
950             =item $old_path = $w->path ($new_path)
951              
952             Returns the previously set path and optionally set a new one.
953              
954             =item $current_interval = $w->interval
955              
956             =item $old_interval = $w->interval ($new_interval)
957              
958             Returns the previously set interval and optionally set a new one. Can be
959             used to query the actual interval used.
960              
961             =back
962              
963              
964             =head3 IDLE WATCHERS - when you've got nothing better to do...
965              
966             =over 4
967              
968             =item $w = EV::idle $callback
969              
970             =item $w = EV::idle_ns $callback
971              
972             =item $w = $loop->idle ($callback)
973              
974             =item $w = $loop->idle_ns ($callback)
975              
976             Call the callback when there are no other pending watchers of the same or
977             higher priority (excluding check, prepare and other idle watchers of the
978             same or lower priority, of course). They are called idle watchers because
979             when the watcher is the highest priority pending event in the process, the
980             process is considered to be idle at that priority.
981              
982             If you want a watcher that is only ever called when I other events are
983             outstanding you have to set the priority to C.
984              
985             The process will not block as long as any idle watchers are active, and
986             they will be called repeatedly until stopped.
987              
988             For example, if you have idle watchers at priority C<0> and C<1>, and
989             an I/O watcher at priority C<0>, then the idle watcher at priority C<1>
990             and the I/O watcher will always run when ready. Only when the idle watcher
991             at priority C<1> is stopped and the I/O watcher at priority C<0> is not
992             pending with the C<0>-priority idle watcher be invoked.
993              
994             The C variant doesn't start (activate) the newly created watcher.
995              
996             =back
997              
998              
999             =head3 PREPARE WATCHERS - customise your event loop!
1000              
1001             =over 4
1002              
1003             =item $w = EV::prepare $callback
1004              
1005             =item $w = EV::prepare_ns $callback
1006              
1007             =item $w = $loop->prepare ($callback)
1008              
1009             =item $w = $loop->prepare_ns ($callback)
1010              
1011             Call the callback just before the process would block. You can still
1012             create/modify any watchers at this point.
1013              
1014             See the EV::check watcher, below, for explanations and an example.
1015              
1016             The C variant doesn't start (activate) the newly created watcher.
1017              
1018             =back
1019              
1020              
1021             =head3 CHECK WATCHERS - customise your event loop even more!
1022              
1023             =over 4
1024              
1025             =item $w = EV::check $callback
1026              
1027             =item $w = EV::check_ns $callback
1028              
1029             =item $w = $loop->check ($callback)
1030              
1031             =item $w = $loop->check_ns ($callback)
1032              
1033             Call the callback just after the process wakes up again (after it has
1034             gathered events), but before any other callbacks have been invoked.
1035              
1036             This can be used to integrate other event-based software into the EV
1037             mainloop: You register a prepare callback and in there, you create io and
1038             timer watchers as required by the other software. Here is a real-world
1039             example of integrating Net::SNMP (with some details left out):
1040              
1041             our @snmp_watcher;
1042              
1043             our $snmp_prepare = EV::prepare sub {
1044             # do nothing unless active
1045             $dispatcher->{_event_queue_h}
1046             or return;
1047              
1048             # make the dispatcher handle any outstanding stuff
1049             ... not shown
1050              
1051             # create an I/O watcher for each and every socket
1052             @snmp_watcher = (
1053             (map { EV::io $_, EV::READ, sub { } }
1054             keys %{ $dispatcher->{_descriptors} }),
1055              
1056             EV::timer +($event->[Net::SNMP::Dispatcher::_ACTIVE]
1057             ? $event->[Net::SNMP::Dispatcher::_TIME] - EV::now : 0),
1058             0, sub { },
1059             );
1060             };
1061              
1062             The callbacks are irrelevant (and are not even being called), the
1063             only purpose of those watchers is to wake up the process as soon as
1064             one of those events occurs (socket readable, or timer timed out). The
1065             corresponding EV::check watcher will then clean up:
1066              
1067             our $snmp_check = EV::check sub {
1068             # destroy all watchers
1069             @snmp_watcher = ();
1070              
1071             # make the dispatcher handle any new stuff
1072             ... not shown
1073             };
1074              
1075             The callbacks of the created watchers will not be called as the watchers
1076             are destroyed before this can happen (remember EV::check gets called
1077             first).
1078              
1079             The C variant doesn't start (activate) the newly created watcher.
1080              
1081             =item EV::CHECK constant issues
1082              
1083             Like all other watcher types, there is a bitmask constant for use in
1084             C<$revents> and other places. The C is special as it has
1085             the same name as the C sub called by Perl. This doesn't cause
1086             big issues on newer perls (beginning with 5.8.9), but it means thatthe
1087             constant must be I, i.e. runtime calls will not work. That means
1088             that as long as you always C and then C you are on the
1089             safe side.
1090              
1091             =back
1092              
1093              
1094             =head3 FORK WATCHERS - the audacity to resume the event loop after a fork
1095              
1096             Fork watchers are called when a C was detected. The invocation
1097             is done before the event loop blocks next and before C watchers
1098             are being called, and only in the child after the fork.
1099              
1100             =over 4
1101              
1102             =item $w = EV::fork $callback
1103              
1104             =item $w = EV::fork_ns $callback
1105              
1106             =item $w = $loop->fork ($callback)
1107              
1108             =item $w = $loop->fork_ns ($callback)
1109              
1110             Call the callback before the event loop is resumed in the child process
1111             after a fork.
1112              
1113             The C variant doesn't start (activate) the newly created watcher.
1114              
1115             =back
1116              
1117              
1118             =head3 EMBED WATCHERS - when one backend isn't enough...
1119              
1120             This is a rather advanced watcher type that lets you embed one event loop
1121             into another (currently only IO events are supported in the embedded
1122             loop, other types of watchers might be handled in a delayed or incorrect
1123             fashion and must not be used).
1124              
1125             See the libev documentation at
1126             L
1127             (locally installed as F) for more details.
1128              
1129             In short, this watcher is most useful on BSD systems without working
1130             kqueue to still be able to handle a large number of sockets:
1131              
1132             my $socket_loop;
1133            
1134             # check wether we use SELECT or POLL _and_ KQUEUE is supported
1135             if (
1136             (EV::backend & (EV::BACKEND_POLL | EV::BACKEND_SELECT))
1137             && (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE)
1138             ) {
1139             # use kqueue for sockets
1140             $socket_loop = new EV::Loop EV::BACKEND_KQUEUE | EV::FLAG_NOENV;
1141             }
1142            
1143             # use the default loop otherwise
1144             $socket_loop ||= EV::default_loop;
1145              
1146             =over 4
1147              
1148             =item $w = EV::embed $otherloop[, $callback]
1149              
1150             =item $w = EV::embed_ns $otherloop[, $callback]
1151              
1152             =item $w = $loop->embed ($otherloop[, $callback])
1153              
1154             =item $w = $loop->embed_ns ($otherloop[, $callback])
1155              
1156             Call the callback when the embedded event loop (C<$otherloop>) has any
1157             I/O activity. The C<$callback> is optional: if it is missing, then the
1158             embedded event loop will be managed automatically (which is recommended),
1159             otherwise you have to invoke C yourself.
1160              
1161             The C variant doesn't start (activate) the newly created watcher.
1162              
1163             =back
1164              
1165             =head3 ASYNC WATCHERS - how to wake up another event loop
1166              
1167             Async watchers are provided by EV, but have little use in perl directly,
1168             as perl neither supports threads running in parallel nor direct access to
1169             signal handlers or other contexts where they could be of value.
1170              
1171             It is, however, possible to use them from the XS level.
1172              
1173             Please see the libev documentation for further details.
1174              
1175             =over 4
1176              
1177             =item $w = EV::async $callback
1178              
1179             =item $w = EV::async_ns $callback
1180              
1181             =item $w = $loop->async ($callback)
1182              
1183             =item $w = $loop->async_ns ($callback)
1184              
1185             =item $w->send
1186              
1187             =item $bool = $w->async_pending
1188              
1189             =back
1190              
1191             =head3 CLEANUP WATCHERS - how to clean up when the event loop goes away
1192              
1193             Cleanup watchers are not supported on the Perl level, they can only be
1194             used via XS currently.
1195              
1196              
1197             =head1 PERL SIGNALS
1198              
1199             While Perl signal handling (C<%SIG>) is not affected by EV, the behaviour
1200             with EV is as the same as any other C library: Perl-signals will only be
1201             handled when Perl runs, which means your signal handler might be invoked
1202             only the next time an event callback is invoked.
1203              
1204             The solution is to use EV signal watchers (see C), which will
1205             ensure proper operations with regards to other event watchers.
1206              
1207             If you cannot do this for whatever reason, you can also force a watcher
1208             to be called on every event loop iteration by installing a C
1209             watcher:
1210              
1211             my $async_check = EV::check sub { };
1212              
1213             This ensures that perl gets into control for a short time to handle any
1214             pending signals, and also ensures (slightly) slower overall operation.
1215              
1216             =head1 ITHREADS
1217              
1218             Ithreads are not supported by this module in any way. Perl pseudo-threads
1219             is evil stuff and must die. Real threads as provided by Coro are fully
1220             supported (and enhanced support is available via L).
1221              
1222             =head1 FORK
1223              
1224             Most of the "improved" event delivering mechanisms of modern operating
1225             systems have quite a few problems with fork(2) (to put it bluntly: it is
1226             not supported and usually destructive). Libev makes it possible to work
1227             around this by having a function that recreates the kernel state after
1228             fork in the child.
1229              
1230             On non-win32 platforms, this module requires the pthread_atfork
1231             functionality to do this automatically for you. This function is quite
1232             buggy on most BSDs, though, so YMMV. The overhead for this is quite
1233             negligible, because everything the function currently does is set a flag
1234             that is checked only when the event loop gets used the next time, so when
1235             you do fork but not use EV, the overhead is minimal.
1236              
1237             On win32, there is no notion of fork so all this doesn't apply, of course.
1238              
1239             =cut
1240              
1241             our $DIED = sub {
1242             warn "EV: error in callback (ignoring): $@";
1243             };
1244              
1245             default_loop
1246             or die 'EV: cannot initialise libev backend. bad $ENV{LIBEV_FLAGS}?';
1247              
1248             1;
1249              
1250             =head1 SEE ALSO
1251              
1252             L - MakeMaker interface to XS API, L
1253             (asynchronous DNS), L (makes Glib/Gtk2 use EV as event
1254             loop), L (embed Glib into EV), L (efficient thread
1255             integration), L (asynchronous SNMP), L for
1256             event-loop agnostic and portable event driven programming.
1257              
1258             =head1 AUTHOR
1259              
1260             Marc Lehmann
1261             http://home.schmorp.de/
1262              
1263             =cut
1264