ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/EV/EV.pm
Revision: 1.54
Committed: Tue Nov 27 07:27:10 2007 UTC (16 years, 5 months ago) by root
Branch: MAIN
Changes since 1.53: +132 -26 lines
Log Message:
*** empty log message ***

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.11 use EV;
8    
9 root 1.20 # TIMERS
10 root 1.11
11     my $w = EV::timer 2, 0, sub {
12     warn "is called after 2s";
13     };
14    
15 root 1.35 my $w = EV::timer 2, 2, sub {
16     warn "is called roughly every 2s (repeat = 2)";
17 root 1.11 };
18    
19     undef $w; # destroy event watcher again
20    
21 root 1.30 my $w = EV::periodic 0, 60, 0, sub {
22 root 1.11 warn "is called every minute, on the minute, exactly";
23     };
24    
25     # IO
26    
27 root 1.20 my $w = EV::io *STDIN, EV::READ, sub {
28 root 1.35 my ($w, $revents) = @_; # all callbacks receive the watcher and event mask
29 root 1.20 warn "stdin is readable, you entered: ", <STDIN>;
30 root 1.11 };
31    
32     # SIGNALS
33    
34     my $w = EV::signal 'QUIT', sub {
35     warn "sigquit received\n";
36     };
37    
38 root 1.16 # CHILD/PID STATUS CHANGES
39    
40     my $w = EV::child 666, sub {
41 root 1.27 my ($w, $revents) = @_;
42     my $status = $w->rstatus;
43 root 1.16 };
44 root 1.54
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 root 1.11
51     # MAINLOOP
52 root 1.39 EV::loop; # loop until EV::unloop is called or all watchers stop
53 root 1.20 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     below is comprehensive, one might also consult the documentation of libev
61     itself (L<http://cvs.schmorp.de/libev/ev.html>) for more subtle details on
62     watcher semantics or some discussion on the available backends, or how to
63     force a specific backend with C<LIBEV_FLAGS>.
64 root 1.1
65     =cut
66    
67     package EV;
68    
69     use strict;
70    
71     BEGIN {
72 root 1.54 our $VERSION = '1.4';
73 root 1.1 use XSLoader;
74     XSLoader::load "EV", $VERSION;
75     }
76    
77 root 1.49 @EV::IO::ISA =
78 root 1.18 @EV::Timer::ISA =
79     @EV::Periodic::ISA =
80     @EV::Signal::ISA =
81     @EV::Idle::ISA =
82     @EV::Prepare::ISA =
83     @EV::Check::ISA =
84 root 1.54 @EV::Child::ISA =
85     @EV::Embed::ISA =
86     @EV::Stat::ISA = "EV::Watcher";
87 root 1.15
88 root 1.8 =head1 BASIC INTERFACE
89 root 1.1
90     =over 4
91    
92 root 1.8 =item $EV::DIED
93    
94     Must contain a reference to a function that is called when a callback
95     throws an exception (with $@ containing thr error). The default prints an
96     informative message and continues.
97    
98     If this callback throws an exception it will be silently ignored.
99    
100 root 1.20 =item $time = EV::time
101    
102     Returns the current time in (fractional) seconds since the epoch.
103    
104 root 1.2 =item $time = EV::now
105    
106 root 1.20 Returns the time the last event loop iteration has been started. This
107     is the time that (relative) timers are based on, and refering to it is
108     usually faster then calling EV::time.
109    
110 root 1.41 =item $method = EV::method
111 root 1.20
112     Returns an integer describing the backend used by libev (EV::METHOD_SELECT
113     or EV::METHOD_EPOLL).
114    
115     =item EV::loop [$flags]
116 root 1.2
117 root 1.20 Begin checking for events and calling callbacks. It returns when a
118 root 1.39 callback calls EV::unloop.
119 root 1.2
120 root 1.20 The $flags argument can be one of the following:
121 root 1.2
122 root 1.20 0 as above
123     EV::LOOP_ONESHOT block at most once (wait, but do not loop)
124     EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait)
125 root 1.2
126 root 1.39 =item EV::unloop [$how]
127 root 1.2
128 root 1.39 When called with no arguments or an argument of EV::UNLOOP_ONE, makes the
129     innermost call to EV::loop return.
130 root 1.2
131 root 1.39 When called with an argument of EV::UNLOOP_ALL, all calls to EV::loop will return as
132 root 1.20 fast as possible.
133 root 1.2
134 root 1.48 =item EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
135 root 1.47
136     This function rolls together an I/O and a timer watcher for a single
137     one-shot event without the need for managing a watcher object.
138    
139     If C<$fh_or_undef> is a filehandle or file descriptor, then C<$events>
140     must be a bitset containing either C<EV::READ>, C<EV::WRITE> or C<EV::READ
141     | EV::WRITE>, indicating the type of I/O event you want to wait for. If
142     you do not want to wait for some I/O event, specify C<undef> for
143     C<$fh_or_undef> and C<0> for C<$events>).
144    
145     If timeout is C<undef> or negative, then there will be no
146     timeout. Otherwise a EV::timer with this value will be started.
147    
148     When an error occurs or either the timeout or I/O watcher triggers, then
149     the callback will be called with the received event set (in general
150     you can expect it to be a combination of C<EV:ERROR>, C<EV::READ>,
151     C<EV::WRITE> and C<EV::TIMEOUT>).
152    
153     EV::once doesn't return anything: the watchers stay active till either
154     of them triggers, then they will be stopped and freed, and the callback
155     invoked.
156    
157 root 1.20 =back
158    
159 root 1.54 =head2 WATCHER OBJECTS
160 root 1.2
161 root 1.20 A watcher is an object that gets created to record your interest in some
162     event. For instance, if you want to wait for STDIN to become readable, you
163     would create an EV::io watcher for that:
164    
165     my $watcher = EV::io *STDIN, EV::READ, sub {
166     my ($watcher, $revents) = @_;
167     warn "yeah, STDIN should not be readable without blocking!\n"
168     };
169 root 1.2
170 root 1.20 All watchers can be active (waiting for events) or inactive (paused). Only
171     active watchers will have their callbacks invoked. All callbacks will be
172     called with at least two arguments: the watcher and a bitmask of received
173     events.
174    
175     Each watcher type has its associated bit in revents, so you can use the
176     same callback for multiple watchers. The event mask is named after the
177     type, i..e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
178     EV::periodic sets EV::PERIODIC and so on, with the exception of IO events
179     (which can set both EV::READ and EV::WRITE bits), and EV::timer (which
180     uses EV::TIMEOUT).
181    
182     In the rare case where one wants to create a watcher but not start it at
183     the same time, each constructor has a variant with a trailing C<_ns> in
184     its name, e.g. EV::io has a non-starting variant EV::io_ns and so on.
185    
186     Please note that a watcher will automatically be stopped when the watcher
187 root 1.23 object is destroyed, so you I<need> to keep the watcher objects returned by
188 root 1.20 the constructors.
189    
190 root 1.23 Also, all methods changing some aspect of a watcher (->set, ->priority,
191     ->fh and so on) automatically stop and start it again if it is active,
192     which means pending events get lost.
193    
194 root 1.54 =head2 COMMON WATCHER METHODS
195 root 1.20
196 root 1.54 This section lists methods common to all watchers.
197 root 1.20
198     =over 4
199 root 1.2
200 root 1.20 =item $w->start
201    
202     Starts a watcher if it isn't active already. Does nothing to an already
203     active watcher. By default, all watchers start out in the active state
204     (see the description of the C<_ns> variants if you need stopped watchers).
205    
206     =item $w->stop
207 root 1.2
208 root 1.20 Stop a watcher if it is active. Also clear any pending events (events that
209     have been received but that didn't yet result in a callback invocation),
210     regardless of wether the watcher was active or not.
211 root 1.2
212 root 1.20 =item $bool = $w->is_active
213 root 1.2
214 root 1.20 Returns true if the watcher is active, false otherwise.
215    
216 root 1.30 =item $current_data = $w->data
217    
218     =item $old_data = $w->data ($new_data)
219    
220     Queries a freely usable data scalar on the watcher and optionally changes
221     it. This is a way to associate custom data with a watcher:
222    
223     my $w = EV::timer 60, 0, sub {
224     warn $_[0]->data;
225     };
226     $w->data ("print me!");
227    
228 root 1.20 =item $current_cb = $w->cb
229    
230     =item $old_cb = $w->cb ($new_cb)
231    
232 root 1.23 Queries the callback on the watcher and optionally changes it. You can do
233     this at any time without the watcher restarting.
234    
235     =item $current_priority = $w->priority
236    
237     =item $old_priority = $w->priority ($new_priority)
238    
239     Queries the priority on the watcher and optionally changes it. Pending
240     watchers with higher priority will be invoked first. The valid range of
241 root 1.24 priorities lies between EV::MAXPRI (default 2) and EV::MINPRI (default
242     -2). If the priority is outside this range it will automatically be
243 root 1.23 normalised to the nearest valid priority.
244    
245 root 1.50 The default priority of any newly-created watcher is 0.
246    
247     Note that the priority semantics have not yet been fleshed out and are
248     subject to almost certain change.
249 root 1.20
250     =item $w->trigger ($revents)
251    
252     Call the callback *now* with the given event mask.
253    
254 root 1.50 =item $previous_state = $w->keepalive ($bool)
255    
256     Normally, C<EV::loop> will return when there are no active watchers
257     (which is a "deadlock" because no progress can be made anymore). This is
258     convinient because it allows you to start your watchers (and your jobs),
259     call C<EV::loop> once and when it returns you know that all your jobs are
260     finished (or they forgot to register some watchers for their task :).
261    
262     Sometimes, however, this gets in your way, for example when you the module
263     that calls C<EV::loop> (usually the main program) is not the same module
264     as a long-living watcher (for example a DNS client module written by
265     somebody else even). Then you might want any outstanding requests to be
266     handled, but you would not want to keep C<EV::loop> from returning just
267     because you happen to have this long-running UDP port watcher.
268    
269     In this case you can clear the keepalive status, which means that even
270     though your watcher is active, it won't keep C<EV::loop> from returning.
271    
272     The initial value for keepalive is true (enabled), and you cna change it
273     any time.
274    
275     Example: Register an IO watcher for some UDP socket but do not keep the
276     event loop from running just because of that watcher.
277    
278     my $udp_socket = ...
279     my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
280     $udp_watcher->keepalive (0);
281 root 1.20
282 root 1.54 =back
283    
284    
285     =head2 WATCHER TYPES
286    
287     Each of the following subsections describes a single watcher type.
288    
289     =head3 IO WATCHERS - is this file descriptor readable or writable?
290    
291     =over 4
292    
293 root 1.20 =item $w = EV::io $fileno_or_fh, $eventmask, $callback
294 root 1.2
295 root 1.20 =item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
296 root 1.7
297 root 1.20 As long as the returned watcher object is alive, call the C<$callback>
298 root 1.54 when at least one of events specified in C<$eventmask> occurs.
299 root 1.2
300 root 1.20 The $eventmask can be one or more of these constants ORed together:
301 root 1.2
302     EV::READ wait until read() wouldn't block anymore
303     EV::WRITE wait until write() wouldn't block anymore
304 root 1.7
305 root 1.20 The C<io_ns> variant doesn't start (activate) the newly created watcher.
306 root 1.2
307 root 1.20 =item $w->set ($fileno_or_fh, $eventmask)
308 root 1.10
309 root 1.20 Reconfigures the watcher, see the constructor above for details. Can be
310     called at any time.
311 root 1.10
312 root 1.20 =item $current_fh = $w->fh
313    
314     =item $old_fh = $w->fh ($new_fh)
315    
316     Returns the previously set filehandle and optionally set a new one.
317 root 1.10
318 root 1.20 =item $current_eventmask = $w->events
319    
320     =item $old_eventmask = $w->events ($new_eventmask)
321 root 1.10
322 root 1.20 Returns the previously set event mask and optionally set a new one.
323 root 1.10
324 root 1.54 =back
325    
326    
327     =head3 TIMER WATCHERS - relative and optionally repeating timeouts
328    
329     =over 4
330 root 1.10
331 root 1.20 =item $w = EV::timer $after, $repeat, $callback
332 root 1.2
333 root 1.20 =item $w = EV::timer_ns $after, $repeat, $callback
334 root 1.2
335 root 1.53 Calls the callback after C<$after> seconds (which may be fractional). If
336     C<$repeat> is non-zero, the timer will be restarted (with the $repeat
337     value as $after) after the callback returns.
338 root 1.2
339 root 1.20 This means that the callback would be called roughly after C<$after>
340 root 1.39 seconds, and then every C<$repeat> seconds. The timer does his best not
341     to drift, but it will not invoke the timer more often then once per event
342     loop iteration, and might drift in other cases. If that isn't acceptable,
343     look at EV::periodic, which can provide long-term stable timers.
344 root 1.2
345 root 1.39 The timer is based on a monotonic clock, that is, if somebody is sitting
346 root 1.20 in front of the machine while the timer is running and changes the system
347     clock, the timer will nevertheless run (roughly) the same time.
348 root 1.2
349 root 1.20 The C<timer_ns> variant doesn't start (activate) the newly created watcher.
350    
351     =item $w->set ($after, $repeat)
352    
353 root 1.54 Reconfigures the watcher, see the constructor above for details. Can be called at
354 root 1.20 any time.
355    
356     =item $w->again
357    
358     Similar to the C<start> method, but has special semantics for repeating timers:
359    
360 root 1.39 If the timer is active and non-repeating, it will be stopped.
361    
362 root 1.20 If the timer is active and repeating, reset the timeout to occur
363     C<$repeat> seconds after now.
364    
365 root 1.39 If the timer is inactive and repeating, start it using the repeat value.
366 root 1.20
367     Otherwise do nothing.
368    
369     This behaviour is useful when you have a timeout for some IO
370     operation. You create a timer object with the same value for C<$after> and
371     C<$repeat>, and then, in the read/write watcher, run the C<again> method
372     on the timeout.
373    
374 root 1.54 =back
375    
376    
377     =head3 PERIODIC WATCHERS - to cron or not to cron?
378    
379     =over 4
380 root 1.20
381 root 1.30 =item $w = EV::periodic $at, $interval, $reschedule_cb, $callback
382 root 1.20
383 root 1.30 =item $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
384    
385     Similar to EV::timer, but is not based on relative timeouts but on
386     absolute times. Apart from creating "simple" timers that trigger "at" the
387     specified time, it can also be used for non-drifting absolute timers and
388     more complex, cron-like, setups that are not adversely affected by time
389     jumps (i.e. when the system clock is changed by explicit date -s or other
390     means such as ntpd). It is also the most complex watcher type in EV.
391    
392     It has three distinct "modes":
393    
394     =over 4
395 root 1.2
396 root 1.30 =item * absolute timer ($interval = $reschedule_cb = 0)
397 root 1.2
398 root 1.30 This time simply fires at the wallclock time C<$at> and doesn't repeat. It
399     will not adjust when a time jump occurs, that is, if it is to be run
400     at January 1st 2011 then it will run when the system time reaches or
401     surpasses this time.
402 root 1.2
403 root 1.30 =item * non-repeating interval timer ($interval > 0, $reschedule_cb = 0)
404 root 1.2
405 root 1.30 In this mode the watcher will always be scheduled to time out at the
406     next C<$at + N * $interval> time (for some integer N) and then repeat,
407     regardless of any time jumps.
408    
409     This can be used to create timers that do not drift with respect to system
410     time:
411    
412     my $hourly = EV::periodic 0, 3600, 0, sub { print "once/hour\n" };
413    
414     That doesn't mean there will always be 3600 seconds in between triggers,
415     but only that the the clalback will be called when the system time shows a
416     full hour (UTC).
417 root 1.2
418 root 1.7 Another way to think about it (for the mathematically inclined) is that
419 root 1.30 EV::periodic will try to run the callback in this mode at the next
420     possible time where C<$time = $at (mod $interval)>, regardless of any time
421     jumps.
422    
423     =item * manual reschedule mode ($reschedule_cb = coderef)
424    
425 root 1.37 In this mode $interval and $at are both being ignored. Instead, each
426     time the periodic watcher gets scheduled, the reschedule callback
427     ($reschedule_cb) will be called with the watcher as first, and the current
428     time as second argument.
429 root 1.30
430 root 1.31 I<This callback MUST NOT stop or destroy this or any other periodic
431     watcher, ever>. If you need to stop it, return 1e30 and stop it
432     afterwards.
433 root 1.30
434     It must return the next time to trigger, based on the passed time value
435     (that is, the lowest time value larger than to the second argument). It
436     will usually be called just before the callback will be triggered, but
437     might be called at other times, too.
438    
439     This can be used to create very complex timers, such as a timer that
440     triggers on each midnight, local time (actually 24 hours after the last
441     midnight, to keep the example simple. If you know a way to do it correctly
442     in about the same space (without requiring elaborate modules), drop me a
443     note :):
444    
445     my $daily = EV::periodic 0, 0, sub {
446     my ($w, $now) = @_;
447    
448     use Time::Local ();
449     my (undef, undef, undef, $d, $m, $y) = localtime $now;
450     86400 + Time::Local::timelocal 0, 0, 0, $d, $m, $y
451     }, sub {
452     print "it's midnight or likely shortly after, now\n";
453     };
454 root 1.7
455 root 1.30 =back
456 root 1.20
457     The C<periodic_ns> variant doesn't start (activate) the newly created watcher.
458 root 1.2
459 root 1.30 =item $w->set ($at, $interval, $reschedule_cb)
460 root 1.11
461 root 1.54 Reconfigures the watcher, see the constructor above for details. Can be called at
462 root 1.20 any time.
463    
464 root 1.30 =item $w->again
465    
466     Simply stops and starts the watcher again.
467    
468 root 1.54 =back
469    
470    
471     =head3 SIGNAL WATCHERS - signal me when a signal gets signalled!
472    
473     =over 4
474 root 1.20
475     =item $w = EV::signal $signal, $callback
476    
477     =item $w = EV::signal_ns $signal, $callback
478 root 1.11
479 root 1.54 Call the callback when $signal is received (the signal can be specified by
480     number or by name, just as with C<kill> or C<%SIG>).
481 root 1.2
482 root 1.11 EV will grab the signal for the process (the kernel only allows one
483 root 1.20 component to receive a signal at a time) when you start a signal watcher,
484     and removes it again when you stop it. Perl does the same when you
485 root 1.54 add/remove callbacks to C<%SIG>, so watch out.
486 root 1.20
487     You can have as many signal watchers per signal as you want.
488 root 1.2
489 root 1.20 The C<signal_ns> variant doesn't start (activate) the newly created watcher.
490 root 1.2
491 root 1.20 =item $w->set ($signal)
492 root 1.2
493 root 1.54 Reconfigures the watcher, see the constructor above for details. Can be
494     called at any time.
495 root 1.20
496 root 1.22 =item $current_signum = $w->signal
497    
498     =item $old_signum = $w->signal ($new_signal)
499    
500     Returns the previously set signal (always as a number not name) and
501     optionally set a new one.
502    
503 root 1.54 =back
504    
505    
506     =head3 CHILD WATCHERS - watch out for process status changes
507    
508     =over 4
509 root 1.20
510     =item $w = EV::child $pid, $callback
511    
512     =item $w = EV::child_ns $pid, $callback
513    
514 root 1.54 Call the callback when a status change for pid C<$pid> (or any pid if
515     C<$pid> is 0) has been received. More precisely: when the process receives
516     a C<SIGCHLD>, EV will fetch the outstanding exit/wait status for all
517 root 1.20 changed/zombie children and call the callback.
518    
519 root 1.54 It is valid (and fully supported) to install a child watcher after a child
520     has exited but before the event loop has started its next iteration (for
521     example, first you C<fork>, then the new child process might exit, and
522     only then do you install a child watcher in the parent for the new pid).
523    
524     You can access both exit (or tracing) status and pid by using the
525     C<rstatus> and C<rpid> methods on the watcher object.
526 root 1.20
527 root 1.54 You can have as many pid watchers per pid as you want, they will all be
528     called.
529 root 1.20
530     The C<child_ns> variant doesn't start (activate) the newly created watcher.
531    
532     =item $w->set ($pid)
533 root 1.1
534 root 1.54 Reconfigures the watcher, see the constructor above for details. Can be called at
535 root 1.20 any time.
536 root 1.2
537 root 1.22 =item $current_pid = $w->pid
538    
539     =item $old_pid = $w->pid ($new_pid)
540    
541     Returns the previously set process id and optionally set a new one.
542    
543 root 1.27 =item $exit_status = $w->rstatus
544    
545     Return the exit/wait status (as returned by waitpid, see the waitpid entry
546     in perlfunc).
547    
548     =item $pid = $w->rpid
549    
550     Return the pid of the awaited child (useful when you have installed a
551     watcher for all pids).
552    
553 root 1.54 =back
554    
555    
556     =head3 IDLE WATCHERS - when you've got nothing better to do...
557    
558     =over 4
559 root 1.2
560 root 1.20 =item $w = EV::idle $callback
561 root 1.2
562 root 1.20 =item $w = EV::idle_ns $callback
563 root 1.2
564 root 1.20 Call the callback when there are no pending io, timer/periodic, signal or
565     child events, i.e. when the process is idle.
566 root 1.2
567 root 1.20 The process will not block as long as any idle watchers are active, and
568     they will be called repeatedly until stopped.
569 root 1.2
570 root 1.20 The C<idle_ns> variant doesn't start (activate) the newly created watcher.
571 root 1.2
572 root 1.54 =back
573    
574    
575     =head3 PREPARE WATCHERS - customise your event loop!
576    
577     =over 4
578 root 1.2
579 root 1.20 =item $w = EV::prepare $callback
580 root 1.1
581 root 1.20 =item $w = EV::prepare_ns $callback
582 root 1.1
583 root 1.20 Call the callback just before the process would block. You can still
584     create/modify any watchers at this point.
585 root 1.1
586 root 1.20 See the EV::check watcher, below, for explanations and an example.
587 root 1.2
588 root 1.20 The C<prepare_ns> variant doesn't start (activate) the newly created watcher.
589 root 1.2
590 root 1.54 =back
591    
592    
593     =head3 CHECK WATCHERS - customise your event loop even more!
594    
595     =over 4
596 root 1.2
597 root 1.20 =item $w = EV::check $callback
598 root 1.2
599 root 1.20 =item $w = EV::check_ns $callback
600 root 1.10
601 root 1.20 Call the callback just after the process wakes up again (after it has
602     gathered events), but before any other callbacks have been invoked.
603 root 1.10
604 root 1.20 This is used to integrate other event-based software into the EV
605     mainloop: You register a prepare callback and in there, you create io and
606     timer watchers as required by the other software. Here is a real-world
607     example of integrating Net::SNMP (with some details left out):
608 root 1.10
609 root 1.20 our @snmp_watcher;
610 root 1.2
611 root 1.20 our $snmp_prepare = EV::prepare sub {
612     # do nothing unless active
613     $dispatcher->{_event_queue_h}
614     or return;
615 root 1.2
616 root 1.20 # make the dispatcher handle any outstanding stuff
617 root 1.45 ... not shown
618 root 1.2
619 root 1.20 # create an IO watcher for each and every socket
620     @snmp_watcher = (
621     (map { EV::io $_, EV::READ, sub { } }
622     keys %{ $dispatcher->{_descriptors} }),
623 root 1.45
624     EV::timer +($event->[Net::SNMP::Dispatcher::_ACTIVE]
625     ? $event->[Net::SNMP::Dispatcher::_TIME] - EV::now : 0),
626     0, sub { },
627 root 1.20 );
628     };
629 root 1.2
630 root 1.45 The callbacks are irrelevant (and are not even being called), the
631     only purpose of those watchers is to wake up the process as soon as
632     one of those events occurs (socket readable, or timer timed out). The
633     corresponding EV::check watcher will then clean up:
634 root 1.2
635 root 1.20 our $snmp_check = EV::check sub {
636     # destroy all watchers
637     @snmp_watcher = ();
638 root 1.2
639 root 1.20 # make the dispatcher handle any new stuff
640 root 1.45 ... not shown
641 root 1.20 };
642 root 1.2
643 root 1.20 The callbacks of the created watchers will not be called as the watchers
644     are destroyed before this cna happen (remember EV::check gets called
645     first).
646 root 1.2
647 root 1.20 The C<check_ns> variant doesn't start (activate) the newly created watcher.
648 root 1.1
649     =back
650    
651 root 1.54 =head3 STAT WATCHERS - did the file stats just change?
652    
653     =over 4
654    
655     =item $w = EV::stat $path, $interval, $callback
656    
657     =item $w = EV::stat_ns $path, $interval, $callback
658    
659     Call the callback when a file status change has been detected on
660     C<$path>. The C<$path> does not need to exist, changing from "path exists"
661     to "path does not exist" is a status change like any other.
662    
663     The C<$interval> is a recommended polling interval for systems where
664     OS-supported change notifications don't exist or are not supported. If
665     you use C<0> then an unspecified default is used (which is highly
666     recommended!), which is to be expected to be around five seconds usually.
667    
668     This watcher type is not meant for massive numbers of stat watchers,
669     as even with OS-supported change notifications, this can be
670     resource-intensive.
671    
672     The C<stat_ns> variant doesn't start (activate) the newly created watcher.
673    
674     =item $w->set ($path, $interval)
675    
676     Reconfigures the watcher, see the constructor above for details. Can be
677     called at any time.
678    
679     =item $current_path = $w->path
680    
681     =item $old_path = $w->path ($new_path)
682    
683     Returns the previously set path and optionally set a new one.
684    
685     =item $current_interval = $w->interval
686    
687     =item $old_interval = $w->interval ($new_interval)
688    
689     Returns the previously set interval and optionally set a new one. Can be
690     used to query the actual interval used.
691    
692     =back
693    
694    
695 root 1.13 =head1 THREADS
696    
697 root 1.45 Threads are not supported by this module in any way. Perl pseudo-threads
698 root 1.46 is evil stuff and must die. As soon as Perl gains real threads I will work
699     on thread support for it.
700    
701     =head1 FORK
702    
703     Most of the "improved" event delivering mechanisms of modern operating
704     systems have quite a few problems with fork(2) (to put it bluntly: it is
705     not supported and usually destructive). Libev makes it possible to work
706     around this by having a function that recreates the kernel state after
707     fork in the child.
708    
709     On non-win32 platforms, this module requires the pthread_atfork
710     functionality to do this automatically for you. This function is quite
711     buggy on most BSDs, though, so YMMV. The overhead for this is quite
712     negligible, because everything the function currently does is set a flag
713     that is checked only when the event loop gets used the next time, so when
714     you do fork but not use EV, the overhead is minimal.
715    
716     On win32, there is no notion of fork so all this doesn't apply, of course.
717 root 1.13
718 root 1.1 =cut
719    
720 root 1.8 our $DIED = sub {
721     warn "EV: error in callback (ignoring): $@";
722     };
723    
724 root 1.28 default_loop
725 root 1.26 or die 'EV: cannot initialise libev backend. bad $ENV{LIBEV_METHODS}?';
726 root 1.1
727     1;
728    
729 root 1.3 =head1 SEE ALSO
730    
731 root 1.54 L<EV::DNS>.
732 root 1.3
733 root 1.1 =head1 AUTHOR
734    
735     Marc Lehmann <schmorp@schmorp.de>
736     http://home.schmorp.de/
737    
738     =cut
739