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