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

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

Diff Legend

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