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

Comparing EV/README (file contents):
Revision 1.2 by root, Sat Oct 27 19:11:27 2007 UTC vs.
Revision 1.9 by root, Mon Nov 12 01:23:21 2007 UTC

1NAME 1NAME
2 EV - perl interface to libevent, monkey.org/~provos/libevent/ 2 EV - perl interface to libev, a high performance full-featured event
3 loop
3 4
4SYNOPSIS 5SYNOPSIS
5 use EV; 6 use EV;
6 7
7 # TIMER 8 # TIMERS
8 9
9 my $w = EV::timer 2, 0, sub { 10 my $w = EV::timer 2, 0, sub {
10 warn "is called after 2s"; 11 warn "is called after 2s";
11 }; 12 };
12 13
13 my $w = EV::timer 2, 1, sub { 14 my $w = EV::timer 2, 2, sub {
14 warn "is called roughly every 2s (repeat = 1)"; 15 warn "is called roughly every 2s (repeat = 2)";
15 }; 16 };
16 17
17 undef $w; # destroy event watcher again 18 undef $w; # destroy event watcher again
18 19
19 # IO
20
21 my $w = EV::timer_abs 0, 60, sub { 20 my $w = EV::periodic 0, 60, 0, sub {
22 warn "is called every minute, on the minute, exactly"; 21 warn "is called every minute, on the minute, exactly";
23 }; 22 };
24 23
24 # IO
25
25 my $w = EV::io \*STDIN, EV::READ | EV::PERSIST, sub { 26 my $w = EV::io *STDIN, EV::READ, sub {
26 my ($w, $events) = @_; # all callbacks get the watcher object and event mask 27 my ($w, $revents) = @_; # all callbacks receive the watcher and event mask
27 if ($events & EV::TIMEOUT) {
28 warn "nothign received on stdin for 10 seconds, retrying";
29 } else {
30 warn "stdin is readable, you entered: ", <STDIN>; 28 warn "stdin is readable, you entered: ", <STDIN>;
31 }
32 }; 29 };
33 $w->timeout (10); 30
31 # SIGNALS
32
33 my $w = EV::signal 'QUIT', sub {
34 warn "sigquit received\n";
35 };
36
37 # CHILD/PID STATUS CHANGES
34 38
39 my $w = EV::child 666, sub {
40 my ($w, $revents) = @_;
41 my $status = $w->rstatus;
42 };
43
35 # MAINLOOP 44 # MAINLOOP
36 EV::dispatch; # loop as long as watchers are active 45 EV::loop; # loop until EV::loop_done is called or all watchers stop
37 EV::loop; # the same thing 46 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled
38 EV::loop EV::LOOP_ONCE; 47 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
39 EV::loop EV::LOOP_ONSHOT;
40 48
41DESCRIPTION 49DESCRIPTION
42 This module provides an interface to libevent 50 This module provides an interface to libev
43 (<http://monkey.org/~provos/libevent/>). You probably should acquaint 51 (<http://software.schmorp.de/pkg/libev.html>).
44 yourself with its documentation and source code to be able to use this
45 module fully.
46 52
47 Please note thta this module disables the libevent EPOLL method by 53BASIC INTERFACE
48 default, see BUGS, below, if you need to enable it.
49
50FUNCTIONAL INTERFACE
51 $EV::NPRI 54 $EV::DIED
52 How many priority levels are available. 55 Must contain a reference to a function that is called when a
56 callback throws an exception (with $@ containing thr error). The
57 default prints an informative message and continues.
58
59 If this callback throws an exception it will be silently ignored.
60
61 $time = EV::time
62 Returns the current time in (fractional) seconds since the epoch.
53 63
54 $time = EV::now 64 $time = EV::now
55 Returns the time in (fractional) seconds since the epoch. 65 Returns the time the last event loop iteration has been started.
66 This is the time that (relative) timers are based on, and refering
67 to it is usually faster then calling EV::time.
56 68
57 $version = EV::version
58 $method = EV::method 69 $method = EV::ev_method
59 Return version string and event polling method used. 70 Returns an integer describing the backend used by libev
71 (EV::METHOD_SELECT or EV::METHOD_EPOLL).
60 72
61 EV::loop $flags # EV::LOOP_ONCE, EV::LOOP_ONESHOT 73 EV::loop [$flags]
62 EV::loopexit $after 74 Begin checking for events and calling callbacks. It returns when a
63 Exit any active loop or dispatch after $after seconds or immediately 75 callback calls EV::loop_done.
64 if $after is missing or zero.
65 76
66 EV::dispatch 77 The $flags argument can be one of the following:
67 Same as "EV::loop 0".
68 78
69 EV::event $callback 79 0 as above
70 Creates a new event watcher waiting for nothing, calling the given 80 EV::LOOP_ONESHOT block at most once (wait, but do not loop)
71 callback. 81 EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait)
72 82
83 EV::loop_done [$how]
84 When called with no arguments or an argument of 1, makes the
85 innermost call to EV::loop return.
86
87 When called with an agrument of 2, all calls to EV::loop will return
88 as fast as possible.
89
90 WATCHER
91 A watcher is an object that gets created to record your interest in some
92 event. For instance, if you want to wait for STDIN to become readable,
93 you would create an EV::io watcher for that:
94
95 my $watcher = EV::io *STDIN, EV::READ, sub {
96 my ($watcher, $revents) = @_;
97 warn "yeah, STDIN should not be readable without blocking!\n"
98 };
99
100 All watchers can be active (waiting for events) or inactive (paused).
101 Only active watchers will have their callbacks invoked. All callbacks
102 will be called with at least two arguments: the watcher and a bitmask of
103 received events.
104
105 Each watcher type has its associated bit in revents, so you can use the
106 same callback for multiple watchers. The event mask is named after the
107 type, i..e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
108 EV::periodic sets EV::PERIODIC and so on, with the exception of IO
109 events (which can set both EV::READ and EV::WRITE bits), and EV::timer
110 (which uses EV::TIMEOUT).
111
112 In the rare case where one wants to create a watcher but not start it at
113 the same time, each constructor has a variant with a trailing "_ns" in
114 its name, e.g. EV::io has a non-starting variant EV::io_ns and so on.
115
116 Please note that a watcher will automatically be stopped when the
117 watcher object is destroyed, so you *need* to keep the watcher objects
118 returned by the constructors.
119
120 Also, all methods changing some aspect of a watcher (->set, ->priority,
121 ->fh and so on) automatically stop and start it again if it is active,
122 which means pending events get lost.
123
124 WATCHER TYPES
125 Now lets move to the existing watcher types and asociated methods.
126
127 The following methods are available for all watchers. Then followes a
128 description of each watcher constructor (EV::io, EV::timer,
129 EV::periodic, EV::signal, EV::child, EV::idle, EV::prepare and
130 EV::check), followed by any type-specific methods (if any).
131
132 $w->start
133 Starts a watcher if it isn't active already. Does nothing to an
134 already active watcher. By default, all watchers start out in the
135 active state (see the description of the "_ns" variants if you need
136 stopped watchers).
137
138 $w->stop
139 Stop a watcher if it is active. Also clear any pending events
140 (events that have been received but that didn't yet result in a
141 callback invocation), regardless of wether the watcher was active or
142 not.
143
144 $bool = $w->is_active
145 Returns true if the watcher is active, false otherwise.
146
147 $current_data = $w->data
148 $old_data = $w->data ($new_data)
149 Queries a freely usable data scalar on the watcher and optionally
150 changes it. This is a way to associate custom data with a watcher:
151
152 my $w = EV::timer 60, 0, sub {
153 warn $_[0]->data;
154 };
155 $w->data ("print me!");
156
157 $current_cb = $w->cb
158 $old_cb = $w->cb ($new_cb)
159 Queries the callback on the watcher and optionally changes it. You
160 can do this at any time without the watcher restarting.
161
162 $current_priority = $w->priority
163 $old_priority = $w->priority ($new_priority)
164 Queries the priority on the watcher and optionally changes it.
165 Pending watchers with higher priority will be invoked first. The
166 valid range of priorities lies between EV::MAXPRI (default 2) and
167 EV::MINPRI (default -2). If the priority is outside this range it
168 will automatically be normalised to the nearest valid priority.
169
170 The default priority of any newly-created weatcher is 0.
171
172 $w->trigger ($revents)
173 Call the callback *now* with the given event mask.
174
73 my $w = EV::io $fileno_or_fh, $eventmask, $callback 175 $w = EV::io $fileno_or_fh, $eventmask, $callback
74 my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback 176 $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
75 As long as the returned watcher object is alive, call the $callback 177 As long as the returned watcher object is alive, call the $callback
76 when the events specified in $eventmask happen. Initially, the 178 when the events specified in $eventmask.
77 timeout is disabled.
78 179
79 Youc an additionall set a timeout to occur on the watcher, but note
80 that this timeout will not be reset when you get an I/O event in the
81 EV::PERSIST case, and reaching a timeout will always stop the
82 watcher even in the EV::PERSIST case.
83
84 If you want a timeout to occur only after a specific time of
85 inactivity, set a repeating timeout and do NOT use EV::PERSIST.
86
87 Eventmask can be one or more of these constants ORed together: 180 The $eventmask can be one or more of these constants ORed together:
88 181
89 EV::READ wait until read() wouldn't block anymore 182 EV::READ wait until read() wouldn't block anymore
90 EV::WRITE wait until write() wouldn't block anymore 183 EV::WRITE wait until write() wouldn't block anymore
91 EV::PERSIST stay active after a (non-timeout) event occured
92 184
93 The "io_ns" variant doesn't add/start the newly created watcher. 185 The "io_ns" variant doesn't start (activate) the newly created
94
95 my $w = EV::timer $after, $repeat, $callback
96 my $w = EV::timer_ns $after, $repeat, $callback
97 Calls the callback after $after seconds. If $repeat is true, the
98 timer will be restarted after the callback returns. This means that
99 the callback would be called roughly every $after seconds, prolonged
100 by the time the callback takes.
101
102 The "timer_ns" variant doesn't add/start the newly created watcher.
103
104 my $w = EV::timer_abs $at, $interval, $callback
105 my $w = EV::timer_abs_ns $at, $interval, $callback
106 Similar to EV::timer, but the time is given as an absolute point in
107 time ($at), plus an optional $interval.
108
109 If the $interval is zero, then the callback will be called at the
110 time $at if that is in the future, or as soon as possible if its in
111 the past. It will not automatically repeat.
112
113 If the $interval is nonzero, then the watcher will always be
114 scheduled to time out at the next "$at + integer * $interval" time.
115
116 This can be used to schedule a callback to run at very regular
117 intervals, as long as the processing time is less then the interval
118 (otherwise obviously events will be skipped).
119
120 Another way to think about it (for the mathematically inclined) is
121 that "timer_abs" will try to tun the callback at the next possible
122 time where "$time = $at (mod $interval)", regardless of any time
123 jumps.
124
125 The "timer_abs_ns" variant doesn't add/start the newly created
126 watcher. 186 watcher.
127 187
128 my $w = EV::signal $signum, $callback 188 $w->set ($fileno_or_fh, $eventmask)
129 my $w = EV::signal_ns $signum, $callback 189 Reconfigures the watcher, see the constructor above for details. Can
130 Call the callback when signal $signum is received. 190 be called at any time.
131
132 The "signal_ns" variant doesn't add/start the newly created watcher.
133
134THE EV::Event CLASS
135 All EV functions creating an event watcher (designated by "my $w ="
136 above) support the following methods on the returned watcher object:
137
138 $w->add ($timeout)
139 Stops and (re-)starts the event watcher, setting the optional
140 timeout to the given value, or clearing the timeout if none is
141 given.
142
143 $w->start
144 Stops and (re-)starts the event watcher without touching the
145 timeout.
146
147 $w->del
148 $w->stop
149 Stop the event watcher if it was started.
150
151 $current_callback = $w->cb
152 $old_callback = $w->cb ($new_callback)
153 Return the previously set callback and optionally set a new one.
154 191
155 $current_fh = $w->fh 192 $current_fh = $w->fh
156 $old_fh = $w->fh ($new_fh) 193 $old_fh = $w->fh ($new_fh)
157 Returns the previously set filehandle and optionally set a new one. 194 Returns the previously set filehandle and optionally set a new one.
158 195
159 $current_eventmask = $w->events 196 $current_eventmask = $w->events
160 $old_eventmask = $w->events ($new_eventmask) 197 $old_eventmask = $w->events ($new_eventmask)
161 Returns the previously set event mask and optionally set a new one. 198 Returns the previously set event mask and optionally set a new one.
162 199
200 $w = EV::timer $after, $repeat, $callback
201 $w = EV::timer_ns $after, $repeat, $callback
202 Calls the callback after $after seconds. If $repeat is non-zero, the
203 timer will be restarted (with the $repeat value as $after) after the
204 callback returns.
205
206 This means that the callback would be called roughly after $after
207 seconds, and then every $repeat seconds. "Roughly" because the time
208 of callback processing is not taken into account, so the timer will
209 slowly drift. If that isn't acceptable, look at EV::periodic.
210
211 The timer is based on a monotonic clock, that is if somebody is
212 sitting in front of the machine while the timer is running and
213 changes the system clock, the timer will nevertheless run (roughly)
214 the same time.
215
216 The "timer_ns" variant doesn't start (activate) the newly created
217 watcher.
218
163 $w->timeout ($after, $repeat) 219 $w->set ($after, $repeat)
164 Resets the timeout (see "EV::timer" for details). 220 Reconfigures the watcher, see the constructor above for details. Can
221 be at any time.
165 222
166 $w->timeout_abs ($at, $interval) 223 $w->again
167 Resets the timeout (see "EV::timer_abs" for details). 224 Similar to the "start" method, but has special semantics for
225 repeating timers:
168 226
169 $w->priority_set ($priority) 227 If the timer is active and repeating, reset the timeout to occur
170 Set the priority of the watcher to $priority (0 <= $priority < 228 $repeat seconds after now.
171 $EV::NPRI).
172 229
173BUGS 230 If the timer is active and non-repeating, it will be stopped.
174 Lots. Libevent itself isn't well tested and rather buggy, and this
175 module is quite new at the moment.
176 231
177 Please note that the epoll method is not, in general, reliable in 232 If the timer is in active and repeating, start it.
178 programs that use fork (even if no libveent calls are being made in the
179 forked process). If your program behaves erratically, try setting the
180 environment variable "EVENT_NOEPOLL" first when running the program.
181 233
182 In general, if you fork, then you can only use the EV module in one of 234 Otherwise do nothing.
183 the children. 235
236 This behaviour is useful when you have a timeout for some IO
237 operation. You create a timer object with the same value for $after
238 and $repeat, and then, in the read/write watcher, run the "again"
239 method on the timeout.
240
241 $w = EV::periodic $at, $interval, $reschedule_cb, $callback
242 $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
243 Similar to EV::timer, but is not based on relative timeouts but on
244 absolute times. Apart from creating "simple" timers that trigger
245 "at" the specified time, it can also be used for non-drifting
246 absolute timers and more complex, cron-like, setups that are not
247 adversely affected by time jumps (i.e. when the system clock is
248 changed by explicit date -s or other means such as ntpd). It is also
249 the most complex watcher type in EV.
250
251 It has three distinct "modes":
252
253 * absolute timer ($interval = $reschedule_cb = 0)
254 This time simply fires at the wallclock time $at and doesn't
255 repeat. It will not adjust when a time jump occurs, that is, if
256 it is to be run at January 1st 2011 then it will run when the
257 system time reaches or surpasses this time.
258
259 * non-repeating interval timer ($interval > 0, $reschedule_cb = 0)
260 In this mode the watcher will always be scheduled to time out at
261 the next "$at + N * $interval" time (for some integer N) and
262 then repeat, regardless of any time jumps.
263
264 This can be used to create timers that do not drift with respect
265 to system time:
266
267 my $hourly = EV::periodic 0, 3600, 0, sub { print "once/hour\n" };
268
269 That doesn't mean there will always be 3600 seconds in between
270 triggers, but only that the the clalback will be called when the
271 system time shows a full hour (UTC).
272
273 Another way to think about it (for the mathematically inclined)
274 is that EV::periodic will try to run the callback in this mode
275 at the next possible time where "$time = $at (mod $interval)",
276 regardless of any time jumps.
277
278 * manual reschedule mode ($reschedule_cb = coderef)
279 In this mode $interval and $at are both being ignored. Instead,
280 each time the periodic watcher gets scheduled, the first
281 callback ($reschedule_cb) will be called with the watcher as
282 first, and the current time as second argument.
283
284 *This callback MUST NOT stop or destroy this or any other
285 periodic watcher, ever*. If you need to stop it, return 1e30 and
286 stop it afterwards.
287
288 It must return the next time to trigger, based on the passed
289 time value (that is, the lowest time value larger than to the
290 second argument). It will usually be called just before the
291 callback will be triggered, but might be called at other times,
292 too.
293
294 This can be used to create very complex timers, such as a timer
295 that triggers on each midnight, local time (actually 24 hours
296 after the last midnight, to keep the example simple. If you know
297 a way to do it correctly in about the same space (without
298 requiring elaborate modules), drop me a note :):
299
300 my $daily = EV::periodic 0, 0, sub {
301 my ($w, $now) = @_;
302
303 use Time::Local ();
304 my (undef, undef, undef, $d, $m, $y) = localtime $now;
305 86400 + Time::Local::timelocal 0, 0, 0, $d, $m, $y
306 }, sub {
307 print "it's midnight or likely shortly after, now\n";
308 };
309
310 The "periodic_ns" variant doesn't start (activate) the newly created
311 watcher.
312
313 $w->set ($at, $interval, $reschedule_cb)
314 Reconfigures the watcher, see the constructor above for details. Can
315 be at any time.
316
317 $w->again
318 Simply stops and starts the watcher again.
319
320 $w = EV::signal $signal, $callback
321 $w = EV::signal_ns $signal, $callback
322 Call the callback when $signal is received (the signal can be
323 specified by number or by name, just as with kill or %SIG).
324
325 EV will grab the signal for the process (the kernel only allows one
326 component to receive a signal at a time) when you start a signal
327 watcher, and removes it again when you stop it. Perl does the same
328 when you add/remove callbacks to %SIG, so watch out.
329
330 You can have as many signal watchers per signal as you want.
331
332 The "signal_ns" variant doesn't start (activate) the newly created
333 watcher.
334
335 $w->set ($signal)
336 Reconfigures the watcher, see the constructor above for details. Can
337 be at any time.
338
339 $current_signum = $w->signal
340 $old_signum = $w->signal ($new_signal)
341 Returns the previously set signal (always as a number not name) and
342 optionally set a new one.
343
344 $w = EV::child $pid, $callback
345 $w = EV::child_ns $pid, $callback
346 Call the callback when a status change for pid $pid (or any pid if
347 $pid is 0) has been received. More precisely: when the process
348 receives a SIGCHLD, EV will fetch the outstanding exit/wait status
349 for all changed/zombie children and call the callback.
350
351 You can access both status and pid by using the "rstatus" and "rpid"
352 methods on the watcher object.
353
354 You can have as many pid watchers per pid as you want.
355
356 The "child_ns" variant doesn't start (activate) the newly created
357 watcher.
358
359 $w->set ($pid)
360 Reconfigures the watcher, see the constructor above for details. Can
361 be at any time.
362
363 $current_pid = $w->pid
364 $old_pid = $w->pid ($new_pid)
365 Returns the previously set process id and optionally set a new one.
366
367 $exit_status = $w->rstatus
368 Return the exit/wait status (as returned by waitpid, see the waitpid
369 entry in perlfunc).
370
371 $pid = $w->rpid
372 Return the pid of the awaited child (useful when you have installed
373 a watcher for all pids).
374
375 $w = EV::idle $callback
376 $w = EV::idle_ns $callback
377 Call the callback when there are no pending io, timer/periodic,
378 signal or child events, i.e. when the process is idle.
379
380 The process will not block as long as any idle watchers are active,
381 and they will be called repeatedly until stopped.
382
383 The "idle_ns" variant doesn't start (activate) the newly created
384 watcher.
385
386 $w = EV::prepare $callback
387 $w = EV::prepare_ns $callback
388 Call the callback just before the process would block. You can still
389 create/modify any watchers at this point.
390
391 See the EV::check watcher, below, for explanations and an example.
392
393 The "prepare_ns" variant doesn't start (activate) the newly created
394 watcher.
395
396 $w = EV::check $callback
397 $w = EV::check_ns $callback
398 Call the callback just after the process wakes up again (after it
399 has gathered events), but before any other callbacks have been
400 invoked.
401
402 This is used to integrate other event-based software into the EV
403 mainloop: You register a prepare callback and in there, you create
404 io and timer watchers as required by the other software. Here is a
405 real-world example of integrating Net::SNMP (with some details left
406 out):
407
408 our @snmp_watcher;
409
410 our $snmp_prepare = EV::prepare sub {
411 # do nothing unless active
412 $dispatcher->{_event_queue_h}
413 or return;
414
415 # make the dispatcher handle any outstanding stuff
416
417 # create an IO watcher for each and every socket
418 @snmp_watcher = (
419 (map { EV::io $_, EV::READ, sub { } }
420 keys %{ $dispatcher->{_descriptors} }),
421 );
422
423 # if there are any timeouts, also create a timer
424 push @snmp_watcher, EV::timer $event->[Net::SNMP::Dispatcher::_TIME] - EV::now, 0, sub { }
425 if $event->[Net::SNMP::Dispatcher::_ACTIVE];
426 };
427
428 The callbacks are irrelevant, the only purpose of those watchers is
429 to wake up the process as soon as one of those events occurs (socket
430 readable, or timer timed out). The corresponding EV::check watcher
431 will then clean up:
432
433 our $snmp_check = EV::check sub {
434 # destroy all watchers
435 @snmp_watcher = ();
436
437 # make the dispatcher handle any new stuff
438 };
439
440 The callbacks of the created watchers will not be called as the
441 watchers are destroyed before this cna happen (remember EV::check
442 gets called first).
443
444 The "check_ns" variant doesn't start (activate) the newly created
445 watcher.
446
447THREADS
448 Threads are not supported by this in any way. Perl pseudo-threads is
449 evil stuff and must die.
184 450
185SEE ALSO 451SEE ALSO
186 L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
187 L<EV::AnyEvent>. 452 L<EV::DNS>, L<EV::AnyEvent>.
188 453
189AUTHOR 454AUTHOR
190 Marc Lehmann <schmorp@schmorp.de> 455 Marc Lehmann <schmorp@schmorp.de>
191 http://home.schmorp.de/ 456 http://home.schmorp.de/
192 457

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines