ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/EV/EV.pm
Revision: 1.107
Committed: Thu Oct 30 08:10:38 2008 UTC (15 years, 6 months ago) by root
Branch: MAIN
CVS Tags: rel-3_48
Changes since 1.106: +1 -1 lines
Log Message:
3.48

File Contents

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