ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/EV/EV.pm
Revision: 1.141
Committed: Tue Oct 22 10:43:05 2013 UTC (10 years, 6 months ago) by root
Branch: MAIN
Changes since 1.140: +1 -1 lines
Log Message:
*** empty log message ***

File Contents

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