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

Diff Legend

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