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

Comparing EV/README (file contents):
Revision 1.5 by root, Thu Nov 1 13:33:12 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, $revents) = @_; # all callbacks get the watcher object and event mask 27 my ($w, $revents) = @_; # all callbacks get the watcher object and event mask
27 if ($revents & 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, $revents) = @_;
37 if ($revents & 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 {
… …
54 }; 39 };
55 40
56 # CHILD/PID STATUS CHANGES 41 # CHILD/PID STATUS CHANGES
57 42
58 my $w = EV::child 666, sub { 43 my $w = EV::child 666, sub {
59 my ($w, $revents, $status) = @_; 44 my ($w, $revents) = @_;
45 # my $pid = $w->rpid;
46 my $status = $w->rstatus;
60 }; 47 };
61 48
62 # MAINLOOP 49 # MAINLOOP
63 EV::dispatch; # loop as long as watchers are active 50 EV::loop; # loop until EV::loop_done is called
64 EV::loop; # the same thing
65 EV::loop EV::LOOP_ONESHOT; # block until some events could be handles 51 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled
66 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
67 53
68DESCRIPTION 54DESCRIPTION
69 This module provides an interface to libev 55 This module provides an interface to libev
70 (<http://software.schmorp.de/pkg/libev.html>). You probably should 56 (<http://software.schmorp.de/pkg/libev.html>).
71 acquaint yourself with its documentation and source code to be able to
72 use this module fully.
73 57
74BASIC INTERFACE 58BASIC INTERFACE
75 $EV::NPRI
76 How many priority levels are available.
77
78 $EV::DIED 59 $EV::DIED
79 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
80 callback throws an exception (with $@ containing thr error). The 61 callback throws an exception (with $@ containing thr error). The
81 default prints an informative message and continues. 62 default prints an informative message and continues.
82 63
83 If this callback throws an exception it will be silently ignored. 64 If this callback throws an exception it will be silently ignored.
84 65
66 $time = EV::time
67 Returns the current time in (fractional) seconds since the epoch.
68
85 $time = EV::now 69 $time = EV::now
86 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.
87 73
88 $version = EV::version
89 $method = EV::method 74 $method = EV::ev_method
90 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).
91 77
92 EV::loop $flags # EV::LOOP_ONCE, EV::LOOP_ONESHOT 78 EV::loop [$flags]
93 EV::loopexit $after 79 Begin checking for events and calling callbacks. It returns when a
94 Exit any active loop or dispatch after $after seconds or immediately 80 callback calls EV::loop_done.
95 if $after is missing or zero.
96 81
97 EV::dispatch 82 The $flags argument can be one of the following:
98 Same as "EV::loop 0".
99 83
100 EV::event $callback 84 0 as above
101 Creates a new event watcher waiting for nothing, calling the given 85 EV::LOOP_ONESHOT block at most once (wait, but do not loop)
102 callback. 86 EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait)
103 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
104 my $w = EV::io $fileno_or_fh, $eventmask, $callback 170 $w = EV::io $fileno_or_fh, $eventmask, $callback
105 my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback 171 $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
106 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
107 when the events specified in $eventmask happen. Initially, the 173 when the events specified in $eventmask.
108 timeout is disabled.
109 174
110 You can additionall set a timeout to occur on the watcher, but note
111 that this timeout will not be reset when you get an I/O event in the
112 EV::PERSIST case, and reaching a timeout will always stop the
113 watcher even in the EV::PERSIST case.
114
115 If you want a timeout to occur only after a specific time of
116 inactivity, set a repeating timeout and do NOT use EV::PERSIST.
117
118 Eventmask can be one or more of these constants ORed together: 175 The $eventmask can be one or more of these constants ORed together:
119 176
120 EV::READ wait until read() wouldn't block anymore 177 EV::READ wait until read() wouldn't block anymore
121 EV::WRITE wait until write() wouldn't block anymore 178 EV::WRITE wait until write() wouldn't block anymore
122 EV::PERSIST stay active after a (non-timeout) event occured
123 179
124 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.
125 182
126 my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback 183 $w->set ($fileno_or_fh, $eventmask)
127 my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback 184 Reconfigures the watcher, see the constructor above for details. Can
128 Same as "io" and "io_ns", but also specifies a timeout (as if there 185 be called at any time.
129 was a call to "$w->timeout ($timout, 1)". The persist flag is not
130 allowed and will automatically be cleared. The watcher will be
131 restarted after each event.
132 186
133 If the timeout is zero or undef, no timeout will be set, and a 187 $current_fh = $w->fh
134 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.
135 190
136 This has the effect of timing out after the specified period of 191 $current_eventmask = $w->events
137 inactivity has happened. 192 $old_eventmask = $w->events ($new_eventmask)
193 Returns the previously set event mask and optionally set a new one.
138 194
139 Due to the design of libevent, this is also relatively inefficient,
140 having one or two io watchers and a separate timeout watcher that
141 you reset on activity (by calling its "start" method) is usually
142 more efficient.
143
144 my $w = EV::timer $after, $repeat, $callback 195 $w = EV::timer $after, $repeat, $callback
145 my $w = EV::timer_ns $after, $repeat, $callback 196 $w = EV::timer_ns $after, $repeat, $callback
146 Calls the callback after $after seconds. If $repeat is true, the 197 Calls the callback after $after seconds. If $repeat is non-zero, the
147 timer will be restarted after the callback returns. This means that 198 timer will be restarted (with the $repeat value as $after) after the
148 the callback would be called roughly every $after seconds, prolonged 199 callback returns.
149 by the time the callback takes.
150 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
151 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.
152 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
153 my $w = EV::timer_abs $at, $interval, $callback 237 $w = EV::periodic_ns $at, $interval, $callback
154 my $w = EV::timer_abs_ns $at, $interval, $callback
155 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
156 time ($at), plus an optional $interval. 239 time ($at), plus an optional $interval.
157 240
158 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
159 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
160 the past. It will not automatically repeat. 243 in the past. It will not automatically repeat.
161 244
162 If the $interval is nonzero, then the watcher will always be 245 If the $interval is nonzero, then the watcher will always be
163 scheduled to time out at the next "$at + integer * $interval" time. 246 scheduled to time out at the next "$at + N * $interval" time.
164 247
165 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
166 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
167 (otherwise obviously events will be skipped). 250 (otherwise obviously events will be skipped).
168 251
169 Another way to think about it (for the mathematically inclined) is 252 Another way to think about it (for the mathematically inclined) is
170 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
171 time where "$time = $at (mod $interval)", regardless of any time 254 time where "$time = $at (mod $interval)", regardless of any time
172 jumps. 255 jumps.
173 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
174 The "timer_abs_ns" variant doesn't add/start the newly created 262 The "periodic_ns" variant doesn't start (activate) the newly created
175 watcher. 263 watcher.
176 264
265 $w->set ($at, $interval)
266 Reconfigures the watcher, see the constructor above for details. Can
267 be at any time.
268
177 my $w = EV::signal $signal, $callback 269 $w = EV::signal $signal, $callback
178 my $w = EV::signal_ns $signal, $callback 270 $w = EV::signal_ns $signal, $callback
179 Call the callback when $signal is received (the signal can be 271 Call the callback when $signal is received (the signal can be
180 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).
181 watchers are persistent no natter what.
182 273
183 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
184 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
185 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
186 add/remove callbacks to %SIG, so watch out. 277 when you add/remove callbacks to %SIG, so watch out.
187 278
188 Unfortunately, only one handler can be registered per signal. Screw 279 You can have as many signal watchers per signal as you want.
189 libevent.
190 280
191 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.
192 283
193THE EV::Event CLASS 284 $w->set ($signal)
194 All EV functions creating an event watcher (designated by "my $w =" 285 Reconfigures the watcher, see the constructor above for details. Can
195 above) support the following methods on the returned watcher object: 286 be at any time.
196 287
197 $w->add ($timeout)
198 Stops and (re-)starts the event watcher, setting the optional
199 timeout to the given value, or clearing the timeout if none is
200 given.
201
202 $w->start
203 Stops and (re-)starts the event watcher without touching the
204 timeout.
205
206 $w->del
207 $w->stop
208 Stop the event watcher if it was started.
209
210 $current_callback = $w->cb
211 $old_callback = $w->cb ($new_callback)
212 Return the previously set callback and optionally set a new one.
213
214 $current_fh = $w->fh
215 $old_fh = $w->fh ($new_fh)
216 Returns the previously set filehandle and optionally set a new one
217 (also clears the EV::SIGNAL flag when setting a filehandle).
218
219 $current_signal = $w->signal 288 $current_signum = $w->signal
220 $old_signal = $w->signal ($new_signal) 289 $old_signum = $w->signal ($new_signal)
221 Returns the previously set signal number and optionally set a new 290 Returns the previously set signal (always as a number not name) and
222 one (also sets the EV::SIGNAL flag when setting a signal). 291 optionally set a new one.
223 292
224 $current_eventmask = $w->events 293 $w = EV::child $pid, $callback
225 $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)
226 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.
227 315
228 $w->timeout ($after, $repeat) 316 $exit_status = $w->rstatus
229 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).
230 319
231 $w->timeout_abs ($at, $interval) 320 $pid = $w->rpid
232 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).
233 323
234 $w->priority_set ($priority) 324 $w = EV::idle $callback
235 Set the priority of the watcher to $priority (0 <= $priority < 325 $w = EV::idle_ns $callback
236 $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.
328
329 The process will not block as long as any idle watchers are active,
330 and they will be called repeatedly until stopped.
331
332 The "idle_ns" variant doesn't start (activate) the newly created
333 watcher.
334
335 $w = EV::prepare $callback
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.
237 395
238THREADS 396THREADS
239 Threads are not supported by this in any way. Perl pseudo-threads is 397 Threads are not supported by this in any way. Perl pseudo-threads is
240 evil and must die. 398 evil stuff and must die.
241 399
242SEE ALSO 400SEE ALSO
243 L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
244 L<EV::AnyEvent>. 401 L<EV::DNS>, L<EV::AnyEvent>.
245 402
246AUTHOR 403AUTHOR
247 Marc Lehmann <schmorp@schmorp.de> 404 Marc Lehmann <schmorp@schmorp.de>
248 http://home.schmorp.de/ 405 http://home.schmorp.de/
249 406

Diff Legend

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