ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/EV/EV.pm
(Generate patch)

Comparing EV/EV.pm (file contents):
Revision 1.31 by root, Thu Nov 8 02:21:02 2007 UTC vs.
Revision 1.72 by root, Thu Dec 20 07:12:57 2007 UTC

10 10
11 my $w = EV::timer 2, 0, sub { 11 my $w = EV::timer 2, 0, sub {
12 warn "is called after 2s"; 12 warn "is called after 2s";
13 }; 13 };
14 14
15 my $w = EV::timer 2, 1, sub { 15 my $w = EV::timer 2, 2, sub {
16 warn "is called roughly every 2s (repeat = 1)"; 16 warn "is called roughly every 2s (repeat = 2)";
17 }; 17 };
18 18
19 undef $w; # destroy event watcher again 19 undef $w; # destroy event watcher again
20 20
21 my $w = EV::periodic 0, 60, 0, sub { 21 my $w = EV::periodic 0, 60, 0, sub {
23 }; 23 };
24 24
25 # IO 25 # IO
26 26
27 my $w = EV::io *STDIN, EV::READ, sub { 27 my $w = EV::io *STDIN, EV::READ, sub {
28 my ($w, $revents) = @_; # all callbacks get the watcher object and event mask 28 my ($w, $revents) = @_; # all callbacks receive the watcher and event mask
29 warn "stdin is readable, you entered: ", <STDIN>; 29 warn "stdin is readable, you entered: ", <STDIN>;
30 }; 30 };
31 31
32 # SIGNALS 32 # SIGNALS
33 33
34 my $w = EV::signal 'QUIT', sub { 34 my $w = EV::signal 'QUIT', sub {
35 warn "sigquit received\n"; 35 warn "sigquit received\n";
36 }; 36 };
37 37
38 my $w = EV::signal 3, sub {
39 warn "sigquit received (this is GNU/Linux, right?)\n";
40 };
41
42 # CHILD/PID STATUS CHANGES 38 # CHILD/PID STATUS CHANGES
43 39
44 my $w = EV::child 666, sub { 40 my $w = EV::child 666, sub {
45 my ($w, $revents) = @_; 41 my ($w, $revents) = @_;
46 # my $pid = $w->rpid;
47 my $status = $w->rstatus; 42 my $status = $w->rstatus;
48 }; 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 };
49 50
50 # MAINLOOP 51 # MAINLOOP
51 EV::loop; # loop until EV::loop_done is called 52 EV::loop; # loop until EV::unloop is called or all watchers stop
52 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled 53 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled
53 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block 54 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
54 55
55=head1 DESCRIPTION 56=head1 DESCRIPTION
56 57
57This module provides an interface to libev 58This module provides an interface to libev
58(L<http://software.schmorp.de/pkg/libev.html>). 59(L<http://software.schmorp.de/pkg/libev.html>). While the documentation
60below is comprehensive, one might also consult the documentation of libev
61itself (L<http://cvs.schmorp.de/libev/ev.html>) for more subtle details on
62watcher semantics or some discussion on the available backends, or how to
63force a specific backend with C<LIBEV_FLAGS>, or just about in any case
64because it has much more detailed information.
59 65
60=cut 66=cut
61 67
62package EV; 68package EV;
63 69
64use strict; 70use strict;
65 71
66BEGIN { 72BEGIN {
67 our $VERSION = '0.51'; 73 our $VERSION = '2.0';
68 use XSLoader; 74 use XSLoader;
69 XSLoader::load "EV", $VERSION; 75 XSLoader::load "EV", $VERSION;
70} 76}
71 77
72@EV::Io::ISA = 78@EV::IO::ISA =
73@EV::Timer::ISA = 79@EV::Timer::ISA =
74@EV::Periodic::ISA = 80@EV::Periodic::ISA =
75@EV::Signal::ISA = 81@EV::Signal::ISA =
82@EV::Child::ISA =
83@EV::Stat::ISA =
76@EV::Idle::ISA = 84@EV::Idle::ISA =
77@EV::Prepare::ISA = 85@EV::Prepare::ISA =
78@EV::Check::ISA = 86@EV::Check::ISA =
79@EV::Child::ISA = "EV::Watcher"; 87@EV::Embed::ISA =
88@EV::Fork::ISA =
89 "EV::Watcher";
90
91@EV::Loop::Default::ISA = "EV::Loop";
80 92
81=head1 BASIC INTERFACE 93=head1 BASIC INTERFACE
82 94
83=over 4 95=over 4
84 96
85=item $EV::DIED 97=item $EV::DIED
86 98
87Must contain a reference to a function that is called when a callback 99Must contain a reference to a function that is called when a callback
88throws an exception (with $@ containing thr error). The default prints an 100throws an exception (with $@ containing the error). The default prints an
89informative message and continues. 101informative message and continues.
90 102
91If this callback throws an exception it will be silently ignored. 103If this callback throws an exception it will be silently ignored.
92 104
93=item $time = EV::time 105=item $time = EV::time
98 110
99Returns the time the last event loop iteration has been started. This 111Returns the time the last event loop iteration has been started. This
100is the time that (relative) timers are based on, and refering to it is 112is the time that (relative) timers are based on, and refering to it is
101usually faster then calling EV::time. 113usually faster then calling EV::time.
102 114
103=item $method = EV::ev_method 115=item $method = EV::method
104 116
105Returns an integer describing the backend used by libev (EV::METHOD_SELECT 117Returns an integer describing the backend used by libev (EV::METHOD_SELECT
106or EV::METHOD_EPOLL). 118or EV::METHOD_EPOLL).
107 119
108=item EV::loop [$flags] 120=item EV::loop [$flags]
109 121
110Begin checking for events and calling callbacks. It returns when a 122Begin checking for events and calling callbacks. It returns when a
111callback calls EV::loop_done. 123callback calls EV::unloop.
112 124
113The $flags argument can be one of the following: 125The $flags argument can be one of the following:
114 126
115 0 as above 127 0 as above
116 EV::LOOP_ONESHOT block at most once (wait, but do not loop) 128 EV::LOOP_ONESHOT block at most once (wait, but do not loop)
117 EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait) 129 EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait)
118 130
119=item EV::loop_done [$how] 131=item EV::unloop [$how]
120 132
121When called with no arguments or an argument of 1, makes the innermost 133When called with no arguments or an argument of EV::UNLOOP_ONE, makes the
122call to EV::loop return. 134innermost call to EV::loop return.
123 135
124When called with an agrument of 2, all calls to EV::loop will return as 136When called with an argument of EV::UNLOOP_ALL, all calls to EV::loop will return as
125fast as possible. 137fast as possible.
126 138
127=back 139=item $count = EV::loop_count
128 140
141Return the number of times the event loop has polled for new
142events. Sometiems useful as a generation counter.
143
144=item EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
145
146This function rolls together an I/O and a timer watcher for a single
147one-shot event without the need for managing a watcher object.
148
149If C<$fh_or_undef> is a filehandle or file descriptor, then C<$events>
150must be a bitset containing either C<EV::READ>, C<EV::WRITE> or C<EV::READ
151| EV::WRITE>, indicating the type of I/O event you want to wait for. If
152you do not want to wait for some I/O event, specify C<undef> for
153C<$fh_or_undef> and C<0> for C<$events>).
154
155If timeout is C<undef> or negative, then there will be no
156timeout. Otherwise a EV::timer with this value will be started.
157
158When an error occurs or either the timeout or I/O watcher triggers, then
159the callback will be called with the received event set (in general
160you can expect it to be a combination of C<EV:ERROR>, C<EV::READ>,
161C<EV::WRITE> and C<EV::TIMEOUT>).
162
163EV::once doesn't return anything: the watchers stay active till either
164of them triggers, then they will be stopped and freed, and the callback
165invoked.
166
167=item EV::feed_fd_event ($fd, $revents)
168
169Feed an event on a file descriptor into EV. EV will react to this call as
170if the readyness notifications specified by C<$revents> (a combination of
171C<EV::READ> and C<EV::WRITE>) happened on the file descriptor C<$fd>.
172
173=item EV::feed_signal_event ($signal)
174
175Feed a signal event into EV. EV will react to this call as if the signal
176specified by C<$signal> had occured.
177
178=back
179
180
129=head2 WATCHER 181=head2 WATCHER OBJECTS
130 182
131A watcher is an object that gets created to record your interest in some 183A watcher is an object that gets created to record your interest in some
132event. For instance, if you want to wait for STDIN to become readable, you 184event. For instance, if you want to wait for STDIN to become readable, you
133would create an EV::io watcher for that: 185would create an EV::io watcher for that:
134 186
143events. 195events.
144 196
145Each watcher type has its associated bit in revents, so you can use the 197Each watcher type has its associated bit in revents, so you can use the
146same callback for multiple watchers. The event mask is named after the 198same callback for multiple watchers. The event mask is named after the
147type, i..e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE, 199type, i..e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
148EV::periodic sets EV::PERIODIC and so on, with the exception of IO events 200EV::periodic sets EV::PERIODIC and so on, with the exception of I/O events
149(which can set both EV::READ and EV::WRITE bits), and EV::timer (which 201(which can set both EV::READ and EV::WRITE bits), and EV::timer (which
150uses EV::TIMEOUT). 202uses EV::TIMEOUT).
151 203
152In the rare case where one wants to create a watcher but not start it at 204In the rare case where one wants to create a watcher but not start it at
153the same time, each constructor has a variant with a trailing C<_ns> in 205the same time, each constructor has a variant with a trailing C<_ns> in
159 211
160Also, all methods changing some aspect of a watcher (->set, ->priority, 212Also, all methods changing some aspect of a watcher (->set, ->priority,
161->fh and so on) automatically stop and start it again if it is active, 213->fh and so on) automatically stop and start it again if it is active,
162which means pending events get lost. 214which means pending events get lost.
163 215
164=head2 WATCHER TYPES 216=head2 COMMON WATCHER METHODS
165 217
166Now lets move to the existing watcher types and asociated methods. 218This section lists methods common to all watchers.
167
168The following methods are available for all watchers. Then followes a
169description of each watcher constructor (EV::io, EV::timer, EV::periodic,
170EV::signal, EV::child, EV::idle, EV::prepare and EV::check), followed by
171any type-specific methods (if any).
172 219
173=over 4 220=over 4
174 221
175=item $w->start 222=item $w->start
176 223
180 227
181=item $w->stop 228=item $w->stop
182 229
183Stop a watcher if it is active. Also clear any pending events (events that 230Stop a watcher if it is active. Also clear any pending events (events that
184have been received but that didn't yet result in a callback invocation), 231have been received but that didn't yet result in a callback invocation),
185regardless of wether the watcher was active or not. 232regardless of whether the watcher was active or not.
186 233
187=item $bool = $w->is_active 234=item $bool = $w->is_active
188 235
189Returns true if the watcher is active, false otherwise. 236Returns true if the watcher is active, false otherwise.
190 237
215watchers with higher priority will be invoked first. The valid range of 262watchers with higher priority will be invoked first. The valid range of
216priorities lies between EV::MAXPRI (default 2) and EV::MINPRI (default 263priorities lies between EV::MAXPRI (default 2) and EV::MINPRI (default
217-2). If the priority is outside this range it will automatically be 264-2). If the priority is outside this range it will automatically be
218normalised to the nearest valid priority. 265normalised to the nearest valid priority.
219 266
220The default priority of any newly-created weatcher is 0. 267The default priority of any newly-created watcher is 0.
221 268
269Note that the priority semantics have not yet been fleshed out and are
270subject to almost certain change.
271
222=item $w->trigger ($revents) 272=item $w->invoke ($revents)
223 273
224Call the callback *now* with the given event mask. 274Call the callback *now* with the given event mask.
225 275
276=item $w->feed_event ($revents)
277
278Feed some events on this watcher into EV. EV will react to this call as if
279the watcher had received the given C<$revents> mask.
280
281=item $revents = $w->clear_pending
282
283If the watcher is pending, this function returns clears its pending status
284and returns its C<$revents> bitset (as if its callback was invoked). If the
285watcher isn't pending it does nothing and returns C<0>.
286
287=item $previous_state = $w->keepalive ($bool)
288
289Normally, C<EV::loop> will return when there are no active watchers
290(which is a "deadlock" because no progress can be made anymore). This is
291convinient because it allows you to start your watchers (and your jobs),
292call C<EV::loop> once and when it returns you know that all your jobs are
293finished (or they forgot to register some watchers for their task :).
294
295Sometimes, however, this gets in your way, for example when you the module
296that calls C<EV::loop> (usually the main program) is not the same module
297as a long-living watcher (for example a DNS client module written by
298somebody else even). Then you might want any outstanding requests to be
299handled, but you would not want to keep C<EV::loop> from returning just
300because you happen to have this long-running UDP port watcher.
301
302In this case you can clear the keepalive status, which means that even
303though your watcher is active, it won't keep C<EV::loop> from returning.
304
305The initial value for keepalive is true (enabled), and you cna change it
306any time.
307
308Example: Register an I/O watcher for some UDP socket but do not keep the
309event loop from running just because of that watcher.
310
311 my $udp_socket = ...
312 my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
313 $udp_watcher->keepalive (0);
314
315=back
316
317
318=head2 WATCHER TYPES
319
320Each of the following subsections describes a single watcher type.
321
322=head3 I/O WATCHERS - is this file descriptor readable or writable?
323
324=over 4
226 325
227=item $w = EV::io $fileno_or_fh, $eventmask, $callback 326=item $w = EV::io $fileno_or_fh, $eventmask, $callback
228 327
229=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback 328=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
230 329
231As long as the returned watcher object is alive, call the C<$callback> 330As long as the returned watcher object is alive, call the C<$callback>
232when the events specified in C<$eventmask>. 331when at least one of events specified in C<$eventmask> occurs.
233 332
234The $eventmask can be one or more of these constants ORed together: 333The $eventmask can be one or more of these constants ORed together:
235 334
236 EV::READ wait until read() wouldn't block anymore 335 EV::READ wait until read() wouldn't block anymore
237 EV::WRITE wait until write() wouldn't block anymore 336 EV::WRITE wait until write() wouldn't block anymore
253 352
254=item $old_eventmask = $w->events ($new_eventmask) 353=item $old_eventmask = $w->events ($new_eventmask)
255 354
256Returns the previously set event mask and optionally set a new one. 355Returns the previously set event mask and optionally set a new one.
257 356
357=back
358
359
360=head3 TIMER WATCHERS - relative and optionally repeating timeouts
361
362=over 4
258 363
259=item $w = EV::timer $after, $repeat, $callback 364=item $w = EV::timer $after, $repeat, $callback
260 365
261=item $w = EV::timer_ns $after, $repeat, $callback 366=item $w = EV::timer_ns $after, $repeat, $callback
262 367
263Calls the callback after C<$after> seconds. If C<$repeat> is non-zero, 368Calls the callback after C<$after> seconds (which may be fractional). If
264the timer will be restarted (with the $repeat value as $after) after the 369C<$repeat> is non-zero, the timer will be restarted (with the $repeat
265callback returns. 370value as $after) after the callback returns.
266 371
267This means that the callback would be called roughly after C<$after> 372This means that the callback would be called roughly after C<$after>
268seconds, and then every C<$repeat> seconds. "Roughly" because the time of 373seconds, and then every C<$repeat> seconds. The timer does his best not
269callback processing is not taken into account, so the timer will slowly 374to drift, but it will not invoke the timer more often then once per event
270drift. If that isn't acceptable, look at EV::periodic. 375loop iteration, and might drift in other cases. If that isn't acceptable,
376look at EV::periodic, which can provide long-term stable timers.
271 377
272The timer is based on a monotonic clock, that is if somebody is sitting 378The timer is based on a monotonic clock, that is, if somebody is sitting
273in front of the machine while the timer is running and changes the system 379in front of the machine while the timer is running and changes the system
274clock, the timer will nevertheless run (roughly) the same time. 380clock, the timer will nevertheless run (roughly) the same time.
275 381
276The C<timer_ns> variant doesn't start (activate) the newly created watcher. 382The C<timer_ns> variant doesn't start (activate) the newly created watcher.
277 383
278=item $w->set ($after, $repeat) 384=item $w->set ($after, $repeat)
279 385
280Reconfigures the watcher, see the constructor above for details. Can be at 386Reconfigures the watcher, see the constructor above for details. Can be called at
281any time. 387any time.
282 388
283=item $w->again 389=item $w->again
284 390
285Similar to the C<start> method, but has special semantics for repeating timers: 391Similar to the C<start> method, but has special semantics for repeating timers:
392
393If the timer is active and non-repeating, it will be stopped.
286 394
287If the timer is active and repeating, reset the timeout to occur 395If the timer is active and repeating, reset the timeout to occur
288C<$repeat> seconds after now. 396C<$repeat> seconds after now.
289 397
290If the timer is active and non-repeating, it will be stopped.
291
292If the timer is in active and repeating, start it. 398If the timer is inactive and repeating, start it using the repeat value.
293 399
294Otherwise do nothing. 400Otherwise do nothing.
295 401
296This behaviour is useful when you have a timeout for some IO 402This behaviour is useful when you have a timeout for some IO
297operation. You create a timer object with the same value for C<$after> and 403operation. You create a timer object with the same value for C<$after> and
298C<$repeat>, and then, in the read/write watcher, run the C<again> method 404C<$repeat>, and then, in the read/write watcher, run the C<again> method
299on the timeout. 405on the timeout.
300 406
407=back
408
409
410=head3 PERIODIC WATCHERS - to cron or not to cron?
411
412=over 4
301 413
302=item $w = EV::periodic $at, $interval, $reschedule_cb, $callback 414=item $w = EV::periodic $at, $interval, $reschedule_cb, $callback
303 415
304=item $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback 416=item $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
305 417
341possible time where C<$time = $at (mod $interval)>, regardless of any time 453possible time where C<$time = $at (mod $interval)>, regardless of any time
342jumps. 454jumps.
343 455
344=item * manual reschedule mode ($reschedule_cb = coderef) 456=item * manual reschedule mode ($reschedule_cb = coderef)
345 457
346In this mode $interval and $at are both being ignored. Instead, each time 458In this mode $interval and $at are both being ignored. Instead, each
347the periodic watcher gets scheduled, the first callback ($reschedule_cb) 459time the periodic watcher gets scheduled, the reschedule callback
348will be called with the watcher as first, and the current time as second 460($reschedule_cb) will be called with the watcher as first, and the current
349argument. 461time as second argument.
350 462
351I<This callback MUST NOT stop or destroy this or any other periodic 463I<This callback MUST NOT stop or destroy this or any other periodic
352watcher, ever>. If you need to stop it, return 1e30 and stop it 464watcher, ever>. If you need to stop it, return 1e30 and stop it
353afterwards. 465afterwards.
354 466
377 489
378The C<periodic_ns> variant doesn't start (activate) the newly created watcher. 490The C<periodic_ns> variant doesn't start (activate) the newly created watcher.
379 491
380=item $w->set ($at, $interval, $reschedule_cb) 492=item $w->set ($at, $interval, $reschedule_cb)
381 493
382Reconfigures the watcher, see the constructor above for details. Can be at 494Reconfigures the watcher, see the constructor above for details. Can be called at
383any time. 495any time.
384 496
385=item $w->again 497=item $w->again
386 498
387Simply stops and starts the watcher again. 499Simply stops and starts the watcher again.
388 500
501=item $time = $w->at
502
503Return the time that the watcher is expected to trigger next.
504
505=back
506
507
508=head3 SIGNAL WATCHERS - signal me when a signal gets signalled!
509
510=over 4
389 511
390=item $w = EV::signal $signal, $callback 512=item $w = EV::signal $signal, $callback
391 513
392=item $w = EV::signal_ns $signal, $callback 514=item $w = EV::signal_ns $signal, $callback
393 515
394Call the callback when $signal is received (the signal can be specified 516Call the callback when $signal is received (the signal can be specified by
395by number or by name, just as with kill or %SIG). 517number or by name, just as with C<kill> or C<%SIG>).
396 518
397EV will grab the signal for the process (the kernel only allows one 519EV will grab the signal for the process (the kernel only allows one
398component to receive a signal at a time) when you start a signal watcher, 520component to receive a signal at a time) when you start a signal watcher,
399and removes it again when you stop it. Perl does the same when you 521and removes it again when you stop it. Perl does the same when you
400add/remove callbacks to %SIG, so watch out. 522add/remove callbacks to C<%SIG>, so watch out.
401 523
402You can have as many signal watchers per signal as you want. 524You can have as many signal watchers per signal as you want.
403 525
404The C<signal_ns> variant doesn't start (activate) the newly created watcher. 526The C<signal_ns> variant doesn't start (activate) the newly created watcher.
405 527
406=item $w->set ($signal) 528=item $w->set ($signal)
407 529
408Reconfigures the watcher, see the constructor above for details. Can be at 530Reconfigures the watcher, see the constructor above for details. Can be
409any time. 531called at any time.
410 532
411=item $current_signum = $w->signal 533=item $current_signum = $w->signal
412 534
413=item $old_signum = $w->signal ($new_signal) 535=item $old_signum = $w->signal ($new_signal)
414 536
415Returns the previously set signal (always as a number not name) and 537Returns the previously set signal (always as a number not name) and
416optionally set a new one. 538optionally set a new one.
417 539
540=back
541
542
543=head3 CHILD WATCHERS - watch out for process status changes
544
545=over 4
418 546
419=item $w = EV::child $pid, $callback 547=item $w = EV::child $pid, $callback
420 548
421=item $w = EV::child_ns $pid, $callback 549=item $w = EV::child_ns $pid, $callback
422 550
423Call the callback when a status change for pid C<$pid> (or any pid 551Call the callback when a status change for pid C<$pid> (or any pid if
424if C<$pid> is 0) has been received. More precisely: when the process 552C<$pid> is 0) has been received. More precisely: when the process receives
425receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all 553a C<SIGCHLD>, EV will fetch the outstanding exit/wait status for all
426changed/zombie children and call the callback. 554changed/zombie children and call the callback.
427 555
428You can access both status and pid by using the C<rstatus> and C<rpid> 556It is valid (and fully supported) to install a child watcher after a child
429methods on the watcher object. 557has exited but before the event loop has started its next iteration (for
558example, first you C<fork>, then the new child process might exit, and
559only then do you install a child watcher in the parent for the new pid).
430 560
561You can access both exit (or tracing) status and pid by using the
562C<rstatus> and C<rpid> methods on the watcher object.
563
431You can have as many pid watchers per pid as you want. 564You can have as many pid watchers per pid as you want, they will all be
565called.
432 566
433The C<child_ns> variant doesn't start (activate) the newly created watcher. 567The C<child_ns> variant doesn't start (activate) the newly created watcher.
434 568
435=item $w->set ($pid) 569=item $w->set ($pid)
436 570
437Reconfigures the watcher, see the constructor above for details. Can be at 571Reconfigures the watcher, see the constructor above for details. Can be called at
438any time. 572any time.
439 573
440=item $current_pid = $w->pid 574=item $current_pid = $w->pid
441 575
442=item $old_pid = $w->pid ($new_pid) 576=item $old_pid = $w->pid ($new_pid)
451=item $pid = $w->rpid 585=item $pid = $w->rpid
452 586
453Return the pid of the awaited child (useful when you have installed a 587Return the pid of the awaited child (useful when you have installed a
454watcher for all pids). 588watcher for all pids).
455 589
590=back
591
592
593=head3 STAT WATCHERS - did the file attributes just change?
594
595=over 4
596
597=item $w = EV::stat $path, $interval, $callback
598
599=item $w = EV::stat_ns $path, $interval, $callback
600
601Call the callback when a file status change has been detected on
602C<$path>. The C<$path> does not need to exist, changing from "path exists"
603to "path does not exist" is a status change like any other.
604
605The C<$interval> is a recommended polling interval for systems where
606OS-supported change notifications don't exist or are not supported. If
607you use C<0> then an unspecified default is used (which is highly
608recommended!), which is to be expected to be around five seconds usually.
609
610This watcher type is not meant for massive numbers of stat watchers,
611as even with OS-supported change notifications, this can be
612resource-intensive.
613
614The C<stat_ns> variant doesn't start (activate) the newly created watcher.
615
616=item ... = $w->stat
617
618This call is very similar to the perl C<stat> built-in: It stats (using
619C<lstat>) the path specified in the watcher and sets perls stat cache (as
620well as EV's idea of the current stat values) to the values found.
621
622In scalar context, a boolean is return indicating success or failure of
623the stat. In list context, the same 13-value list as with stat is returned
624(except that the blksize and blocks fields are not reliable).
625
626In the case of an error, errno is set to C<ENOENT> (regardless of the
627actual error value) and the C<nlink> value is forced to zero (if the stat
628was successful then nlink is guaranteed to be non-zero).
629
630See also the next two entries for more info.
631
632=item ... = $w->attr
633
634Just like C<< $w->stat >>, but without the initial stat'ing: this returns
635the values most recently detected by EV. See the next entry for more info.
636
637=item ... = $w->prev
638
639Just like C<< $w->stat >>, but without the initial stat'ing: this returns
640the previous set of values, before the change.
641
642That is, when the watcher callback is invoked, C<< $w->prev >> will be set
643to the values found I<before> a change was detected, while C<< $w->attr >>
644returns the values found leading to the change detection. The difference (if any)
645between C<prev> and C<attr> is what triggered the callback.
646
647If you did something to the filesystem object and do not want to trigger
648yet another change, you can call C<stat> to update EV's idea of what the
649current attributes are.
650
651=item $w->set ($path, $interval)
652
653Reconfigures the watcher, see the constructor above for details. Can be
654called at any time.
655
656=item $current_path = $w->path
657
658=item $old_path = $w->path ($new_path)
659
660Returns the previously set path and optionally set a new one.
661
662=item $current_interval = $w->interval
663
664=item $old_interval = $w->interval ($new_interval)
665
666Returns the previously set interval and optionally set a new one. Can be
667used to query the actual interval used.
668
669=back
670
671
672=head3 IDLE WATCHERS - when you've got nothing better to do...
673
674=over 4
456 675
457=item $w = EV::idle $callback 676=item $w = EV::idle $callback
458 677
459=item $w = EV::idle_ns $callback 678=item $w = EV::idle_ns $callback
460 679
461Call the callback when there are no pending io, timer/periodic, signal or 680Call the callback when there are no other pending watchers of the same or
462child events, i.e. when the process is idle. 681higher priority (excluding check, prepare and other idle watchers of the
682same or lower priority, of course). They are called idle watchers because
683when the watcher is the highest priority pending event in the process, the
684process is considered to be idle at that priority.
685
686If you want a watcher that is only ever called when I<no> other events are
687outstanding you have to set the priority to C<EV::MINPRI>.
463 688
464The process will not block as long as any idle watchers are active, and 689The process will not block as long as any idle watchers are active, and
465they will be called repeatedly until stopped. 690they will be called repeatedly until stopped.
466 691
692For example, if you have idle watchers at priority C<0> and C<1>, and
693an I/O watcher at priority C<0>, then the idle watcher at priority C<1>
694and the I/O watcher will always run when ready. Only when the idle watcher
695at priority C<1> is stopped and the I/O watcher at priority C<0> is not
696pending with the C<0>-priority idle watcher be invoked.
697
467The C<idle_ns> variant doesn't start (activate) the newly created watcher. 698The C<idle_ns> variant doesn't start (activate) the newly created watcher.
468 699
700=back
701
702
703=head3 PREPARE WATCHERS - customise your event loop!
704
705=over 4
469 706
470=item $w = EV::prepare $callback 707=item $w = EV::prepare $callback
471 708
472=item $w = EV::prepare_ns $callback 709=item $w = EV::prepare_ns $callback
473 710
476 713
477See the EV::check watcher, below, for explanations and an example. 714See the EV::check watcher, below, for explanations and an example.
478 715
479The C<prepare_ns> variant doesn't start (activate) the newly created watcher. 716The C<prepare_ns> variant doesn't start (activate) the newly created watcher.
480 717
718=back
719
720
721=head3 CHECK WATCHERS - customise your event loop even more!
722
723=over 4
481 724
482=item $w = EV::check $callback 725=item $w = EV::check $callback
483 726
484=item $w = EV::check_ns $callback 727=item $w = EV::check_ns $callback
485 728
497 # do nothing unless active 740 # do nothing unless active
498 $dispatcher->{_event_queue_h} 741 $dispatcher->{_event_queue_h}
499 or return; 742 or return;
500 743
501 # make the dispatcher handle any outstanding stuff 744 # make the dispatcher handle any outstanding stuff
745 ... not shown
502 746
503 # create an IO watcher for each and every socket 747 # create an I/O watcher for each and every socket
504 @snmp_watcher = ( 748 @snmp_watcher = (
505 (map { EV::io $_, EV::READ, sub { } } 749 (map { EV::io $_, EV::READ, sub { } }
506 keys %{ $dispatcher->{_descriptors} }), 750 keys %{ $dispatcher->{_descriptors} }),
751
752 EV::timer +($event->[Net::SNMP::Dispatcher::_ACTIVE]
753 ? $event->[Net::SNMP::Dispatcher::_TIME] - EV::now : 0),
754 0, sub { },
507 ); 755 );
508
509 # if there are any timeouts, also create a timer
510 push @snmp_watcher, EV::timer $event->[Net::SNMP::Dispatcher::_TIME] - EV::now, 0, sub { }
511 if $event->[Net::SNMP::Dispatcher::_ACTIVE];
512 }; 756 };
513 757
514The callbacks are irrelevant, the only purpose of those watchers is 758The callbacks are irrelevant (and are not even being called), the
515to wake up the process as soon as one of those events occurs (socket 759only purpose of those watchers is to wake up the process as soon as
516readable, or timer timed out). The corresponding EV::check watcher will then 760one of those events occurs (socket readable, or timer timed out). The
517clean up: 761corresponding EV::check watcher will then clean up:
518 762
519 our $snmp_check = EV::check sub { 763 our $snmp_check = EV::check sub {
520 # destroy all watchers 764 # destroy all watchers
521 @snmp_watcher = (); 765 @snmp_watcher = ();
522 766
523 # make the dispatcher handle any new stuff 767 # make the dispatcher handle any new stuff
768 ... not shown
524 }; 769 };
525 770
526The callbacks of the created watchers will not be called as the watchers 771The callbacks of the created watchers will not be called as the watchers
527are destroyed before this cna happen (remember EV::check gets called 772are destroyed before this cna happen (remember EV::check gets called
528first). 773first).
529 774
530The C<check_ns> variant doesn't start (activate) the newly created watcher. 775The C<check_ns> variant doesn't start (activate) the newly created watcher.
531 776
532=back 777=back
533 778
779
780=head3 FORK WATCHERS - the audacity to resume the event loop after a fork
781
782Fork watchers are called when a C<fork ()> was detected. The invocation
783is done before the event loop blocks next and before C<check> watchers
784are being called, and only in the child after the fork.
785
786=over 4
787
788=item $w = EV::fork $callback
789
790=item $w = EV::fork_ns $callback
791
792Call the callback before the event loop is resumed in the child process
793after a fork.
794
795The C<fork_ns> variant doesn't start (activate) the newly created watcher.
796
797=back
798
799
800=head1 PERL SIGNALS
801
802While Perl signal handling (C<%SIG>) is not affected by EV, the behaviour
803with EV is as the same as any other C library: Perl-signals will only be
804handled when Perl runs, which means your signal handler might be invoked
805only the next time an event callback is invoked.
806
807The solution is to use EV signal watchers (see C<EV::signal>), which will
808ensure proper operations with regards to other event watchers.
809
810If you cannot do this for whatever reason, you can also force a watcher
811to be called on every event loop iteration by installing a C<EV::check>
812watcher:
813
814 my $async_check = EV::check sub { };
815
816This ensures that perl shortly gets into control for a short time, and
817also ensures slower overall operation.
818
534=head1 THREADS 819=head1 THREADS
535 820
536Threads are not supported by this in any way. Perl pseudo-threads is evil 821Threads are not supported by this module in any way. Perl pseudo-threads
537stuff and must die. 822is evil stuff and must die. As soon as Perl gains real threads I will work
823on thread support for it.
824
825=head1 FORK
826
827Most of the "improved" event delivering mechanisms of modern operating
828systems have quite a few problems with fork(2) (to put it bluntly: it is
829not supported and usually destructive). Libev makes it possible to work
830around this by having a function that recreates the kernel state after
831fork in the child.
832
833On non-win32 platforms, this module requires the pthread_atfork
834functionality to do this automatically for you. This function is quite
835buggy on most BSDs, though, so YMMV. The overhead for this is quite
836negligible, because everything the function currently does is set a flag
837that is checked only when the event loop gets used the next time, so when
838you do fork but not use EV, the overhead is minimal.
839
840On win32, there is no notion of fork so all this doesn't apply, of course.
538 841
539=cut 842=cut
540 843
541our $DIED = sub { 844our $DIED = sub {
542 warn "EV: error in callback (ignoring): $@"; 845 warn "EV: error in callback (ignoring): $@";
543}; 846};
544 847
545default_loop 848default_loop
546 or die 'EV: cannot initialise libev backend. bad $ENV{LIBEV_METHODS}?'; 849 or die 'EV: cannot initialise libev backend. bad $ENV{LIBEV_FLAGS}?';
547
548push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
549 850
5501; 8511;
551 852
552=head1 SEE ALSO 853=head1 SEE ALSO
553 854
554 L<EV::DNS>, L<EV::AnyEvent>. 855L<EV::ADNS> (asynchronous dns), L<Glib::EV> (makes Glib/Gtk2 use EV as
856event loop), L<Coro::EV> (efficient coroutines with EV).
555 857
556=head1 AUTHOR 858=head1 AUTHOR
557 859
558 Marc Lehmann <schmorp@schmorp.de> 860 Marc Lehmann <schmorp@schmorp.de>
559 http://home.schmorp.de/ 861 http://home.schmorp.de/

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines