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

Comparing EV/EV.pm (file contents):
Revision 1.42 by root, Sat Nov 17 01:41:33 2007 UTC vs.
Revision 1.99 by root, Tue Jul 8 09:37:37 2008 UTC

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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines