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

Comparing EV/README (file contents):
Revision 1.3 by root, Sun Oct 28 06:40:46 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
13 my $w = EV::timer 2, 1, sub { 14 my $w = EV::timer 2, 1, sub {
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 # IO
20
21 my $w = EV::timer_abs 0, 60, sub { 20 my $w = EV::periodic 0, 60, 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 get the watcher object 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 my $w = EV::signal 3, sub {
38 warn "sigquit received (this is GNU/Linux, right?)\n";
39 };
34 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 };
48
35 # MAINLOOP 49 # MAINLOOP
36 EV::dispatch; # loop as long as watchers are active 50 EV::loop; # loop until EV::loop_done is called
37 EV::loop; # the same thing 51 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled
38 EV::loop EV::LOOP_ONCE; 52 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
39 EV::loop EV::LOOP_ONSHOT;
40 53
41DESCRIPTION 54DESCRIPTION
42 This module provides an interface to libevent 55 This module provides an interface to libev
43 (<http://monkey.org/~provos/libevent/>). You probably should acquaint 56 (<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
47 Please note thta this module disables the libevent EPOLL method by
48 default, see BUGS, below, if you need to enable it.
49 57
50BASIC INTERFACE 58BASIC INTERFACE
51 $EV::NPRI
52 How many priority levels are available.
53
54 $EV::DIED 59 $EV::DIED
55 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
56 callback throws an exception (with $@ containing thr error). The 61 callback throws an exception (with $@ containing thr error). The
57 default prints an informative message and continues. 62 default prints an informative message and continues.
58 63
59 If this callback throws an exception it will be silently ignored. 64 If this callback throws an exception it will be silently ignored.
60 65
66 $time = EV::time
67 Returns the current time in (fractional) seconds since the epoch.
68
61 $time = EV::now 69 $time = EV::now
62 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.
63 73
64 $version = EV::version
65 $method = EV::method 74 $method = EV::ev_method
66 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).
67 77
68 EV::loop $flags # EV::LOOP_ONCE, EV::LOOP_ONESHOT 78 EV::loop [$flags]
69 EV::loopexit $after 79 Begin checking for events and calling callbacks. It returns when a
70 Exit any active loop or dispatch after $after seconds or immediately 80 callback calls EV::loop_done.
71 if $after is missing or zero.
72 81
73 EV::dispatch 82 The $flags argument can be one of the following:
74 Same as "EV::loop 0".
75 83
76 EV::event $callback 84 0 as above
77 Creates a new event watcher waiting for nothing, calling the given 85 EV::LOOP_ONESHOT block at most once (wait, but do not loop)
78 callback. 86 EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait)
79 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
80 my $w = EV::io $fileno_or_fh, $eventmask, $callback 170 $w = EV::io $fileno_or_fh, $eventmask, $callback
81 my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback 171 $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
82 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
83 when the events specified in $eventmask happen. Initially, the 173 when the events specified in $eventmask.
84 timeout is disabled.
85 174
86 Youc an additionall set a timeout to occur on the watcher, but note
87 that this timeout will not be reset when you get an I/O event in the
88 EV::PERSIST case, and reaching a timeout will always stop the
89 watcher even in the EV::PERSIST case.
90
91 If you want a timeout to occur only after a specific time of
92 inactivity, set a repeating timeout and do NOT use EV::PERSIST.
93
94 Eventmask can be one or more of these constants ORed together: 175 The $eventmask can be one or more of these constants ORed together:
95 176
96 EV::READ wait until read() wouldn't block anymore 177 EV::READ wait until read() wouldn't block anymore
97 EV::WRITE wait until write() wouldn't block anymore 178 EV::WRITE wait until write() wouldn't block anymore
98 EV::PERSIST stay active after a (non-timeout) event occured
99 179
100 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.
101 182
183 $w->set ($fileno_or_fh, $eventmask)
184 Reconfigures the watcher, see the constructor above for details. Can
185 be called at any time.
186
187 $current_fh = $w->fh
188 $old_fh = $w->fh ($new_fh)
189 Returns the previously set filehandle and optionally set a new one.
190
191 $current_eventmask = $w->events
192 $old_eventmask = $w->events ($new_eventmask)
193 Returns the previously set event mask and optionally set a new one.
194
102 my $w = EV::timer $after, $repeat, $callback 195 $w = EV::timer $after, $repeat, $callback
103 my $w = EV::timer_ns $after, $repeat, $callback 196 $w = EV::timer_ns $after, $repeat, $callback
104 Calls the callback after $after seconds. If $repeat is true, the 197 Calls the callback after $after seconds. If $repeat is non-zero, the
105 timer will be restarted after the callback returns. This means that 198 timer will be restarted (with the $repeat value as $after) after the
106 the callback would be called roughly every $after seconds, prolonged 199 callback returns.
107 by the time the callback takes.
108 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
109 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.
110 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
111 my $w = EV::timer_abs $at, $interval, $callback 237 $w = EV::periodic_ns $at, $interval, $callback
112 my $w = EV::timer_abs_ns $at, $interval, $callback
113 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
114 time ($at), plus an optional $interval. 239 time ($at), plus an optional $interval.
115 240
116 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
117 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
118 the past. It will not automatically repeat. 243 in the past. It will not automatically repeat.
119 244
120 If the $interval is nonzero, then the watcher will always be 245 If the $interval is nonzero, then the watcher will always be
121 scheduled to time out at the next "$at + integer * $interval" time. 246 scheduled to time out at the next "$at + N * $interval" time.
122 247
123 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
124 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
125 (otherwise obviously events will be skipped). 250 (otherwise obviously events will be skipped).
126 251
127 Another way to think about it (for the mathematically inclined) is 252 Another way to think about it (for the mathematically inclined) is
128 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
129 time where "$time = $at (mod $interval)", regardless of any time 254 time where "$time = $at (mod $interval)", regardless of any time
130 jumps. 255 jumps.
131 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
132 The "timer_abs_ns" variant doesn't add/start the newly created 262 The "periodic_ns" variant doesn't start (activate) the newly created
133 watcher. 263 watcher.
134 264
265 $w->set ($at, $interval)
266 Reconfigures the watcher, see the constructor above for details. Can
267 be at any time.
268
135 my $w = EV::signal $signum, $callback 269 $w = EV::signal $signal, $callback
136 my $w = EV::signal_ns $signum, $callback 270 $w = EV::signal_ns $signal, $callback
137 Call the callback when signal $signum is received. 271 Call the callback when $signal is received (the signal can be
272 specified by number or by name, just as with kill or %SIG).
138 273
274 EV will grab the signal for the process (the kernel only allows one
275 component to receive a signal at a time) when you start a signal
276 watcher, and removes it again when you stop it. Perl does the same
277 when you add/remove callbacks to %SIG, so watch out.
278
279 You can have as many signal watchers per signal as you want.
280
139 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.
140 283
141THE EV::Event CLASS 284 $w->set ($signal)
142 All EV functions creating an event watcher (designated by "my $w =" 285 Reconfigures the watcher, see the constructor above for details. Can
143 above) support the following methods on the returned watcher object: 286 be at any time.
144 287
145 $w->add ($timeout) 288 $current_signum = $w->signal
146 Stops and (re-)starts the event watcher, setting the optional 289 $old_signum = $w->signal ($new_signal)
147 timeout to the given value, or clearing the timeout if none is 290 Returns the previously set signal (always as a number not name) and
148 given. 291 optionally set a new one.
149 292
150 $w->start 293 $w = EV::child $pid, $callback
151 Stops and (re-)starts the event watcher without touching the 294 $w = EV::child_ns $pid, $callback
152 timeout. 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.
153 299
154 $w->del 300 You can access both status and pid by using the "rstatus" and "rpid"
155 $w->stop 301 methods on the watcher object.
156 Stop the event watcher if it was started.
157 302
158 $current_callback = $w->cb 303 You can have as many pid watchers per pid as you want.
159 $old_callback = $w->cb ($new_callback)
160 Return the previously set callback and optionally set a new one.
161 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
162 $current_fh = $w->fh 312 $current_pid = $w->pid
163 $old_fh = $w->fh ($new_fh) 313 $old_pid = $w->pid ($new_pid)
164 Returns the previously set filehandle and optionally set a new one.
165
166 $current_eventmask = $w->events
167 $old_eventmask = $w->events ($new_eventmask)
168 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.
169 315
170 $w->timeout ($after, $repeat) 316 $exit_status = $w->rstatus
171 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).
172 319
173 $w->timeout_abs ($at, $interval) 320 $pid = $w->rpid
174 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).
175 323
176 $w->priority_set ($priority) 324 $w = EV::idle $callback
177 Set the priority of the watcher to $priority (0 <= $priority < 325 $w = EV::idle_ns $callback
178 $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.
179 328
180BUGS 329 The process will not block as long as any idle watchers are active,
181 Lots. Libevent itself isn't well tested and rather buggy, and this 330 and they will be called repeatedly until stopped.
182 module is quite new at the moment.
183 331
184 Please note that the epoll method is not, in general, reliable in 332 The "idle_ns" variant doesn't start (activate) the newly created
185 programs that use fork (even if no libveent calls are being made in the 333 watcher.
186 forked process). If your program behaves erratically, try setting the
187 environment variable "EVENT_NOEPOLL" first when running the program.
188 334
189 In general, if you fork, then you can only use the EV module in one of 335 $w = EV::prepare $callback
190 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.
191 399
192SEE ALSO 400SEE ALSO
193 L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
194 L<EV::AnyEvent>. 401 L<EV::DNS>, L<EV::AnyEvent>.
195 402
196AUTHOR 403AUTHOR
197 Marc Lehmann <schmorp@schmorp.de> 404 Marc Lehmann <schmorp@schmorp.de>
198 http://home.schmorp.de/ 405 http://home.schmorp.de/
199 406

Diff Legend

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