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.4 by root, Mon Oct 29 19:53:21 2007 UTC

1NAME 1NAME
2 EV - perl interface to libevent, monkey.org/~provos/libevent/ 2 EV - perl interface to libevent, monkey.org/~provos/libevent/
3 3
4SYNOPSIS 4SYNOPSIS
5 use EV; 5 use EV;
6 6
7 # TIMER 7 # TIMER
8 8
9 my $w = EV::timer 2, 0, sub { 9 my $w = EV::timer 2, 0, sub {
10 warn "is called after 2s"; 10 warn "is called after 2s";
11 }; 11 };
12 12
13 my $w = EV::timer 2, 1, sub { 13 my $w = EV::timer 2, 1, sub {
14 warn "is called roughly every 2s (repeat = 1)"; 14 warn "is called roughly every 2s (repeat = 1)";
15 }; 15 };
16 16
17 undef $w; # destroy event watcher again 17 undef $w; # destroy event watcher again
18 18
19 # IO
20
21 my $w = EV::timer_abs 0, 60, sub { 19 my $w = EV::timer_abs 0, 60, sub {
22 warn "is called every minute, on the minute, exactly"; 20 warn "is called every minute, on the minute, exactly";
23 }; 21 };
24 22
23 # IO
24
25 my $w = EV::io \*STDIN, EV::READ | EV::PERSIST, sub { 25 my $w = EV::io \*STDIN, EV::READ | EV::PERSIST, sub {
26 my ($w, $events) = @_; # all callbacks get the watcher object and event mask 26 my ($w, $events) = @_; # all callbacks get the watcher object and event mask
27 if ($events & EV::TIMEOUT) { 27 if ($events & EV::TIMEOUT) {
28 warn "nothign received on stdin for 10 seconds, retrying"; 28 warn "nothing received on stdin for 10 seconds, retrying";
29 } else { 29 } else {
30 warn "stdin is readable, you entered: ", <STDIN>; 30 warn "stdin is readable, you entered: ", <STDIN>;
31 } 31 }
32 }; 32 };
33 $w->timeout (10); 33 $w->timeout (10);
34 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 };
45
46 # SIGNALS
47
48 my $w = EV::signal 'QUIT', sub {
49 warn "sigquit received\n";
50 };
51
52 my $w = EV::signal 3, sub {
53 warn "sigquit received (this is GNU/Linux, right?)\n";
54 };
55
35 # MAINLOOP 56 # MAINLOOP
36 EV::dispatch; # loop as long as watchers are active 57 EV::dispatch; # loop as long as watchers are active
37 EV::loop; # the same thing 58 EV::loop; # the same thing
38 EV::loop EV::LOOP_ONCE; 59 EV::loop EV::LOOP_ONCE; # block until some events could be handles
39 EV::loop EV::LOOP_ONSHOT; 60 EV::loop EV::LOOP_NONBLOCK; # check and handle some events, but do not wait
40 61
41DESCRIPTION 62DESCRIPTION
42 This module provides an interface to libevent 63 This module provides an interface to libevent
43 (<http://monkey.org/~provos/libevent/>). You probably should acquaint 64 (<http://monkey.org/~provos/libevent/>). You probably should acquaint
44 yourself with its documentation and source code to be able to use this 65 yourself with its documentation and source code to be able to use this
… …
81 my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback 102 my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
82 As long as the returned watcher object is alive, call the $callback 103 As long as the returned watcher object is alive, call the $callback
83 when the events specified in $eventmask happen. Initially, the 104 when the events specified in $eventmask happen. Initially, the
84 timeout is disabled. 105 timeout is disabled.
85 106
86 Youc an additionall set a timeout to occur on the watcher, but note 107 You can 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 108 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 109 EV::PERSIST case, and reaching a timeout will always stop the
89 watcher even in the EV::PERSIST case. 110 watcher even in the EV::PERSIST case.
90 111
91 If you want a timeout to occur only after a specific time of 112 If you want a timeout to occur only after a specific time of
… …
96 EV::READ wait until read() wouldn't block anymore 117 EV::READ wait until read() wouldn't block anymore
97 EV::WRITE wait until write() wouldn't block anymore 118 EV::WRITE wait until write() wouldn't block anymore
98 EV::PERSIST stay active after a (non-timeout) event occured 119 EV::PERSIST stay active after a (non-timeout) event occured
99 120
100 The "io_ns" variant doesn't add/start the newly created watcher. 121 The "io_ns" variant doesn't add/start the newly created watcher.
122
123 my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback
124 my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback
125 Same as "io" and "io_ns", but also specifies a timeout (as if there
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
130 If the timeout is zero or undef, no timeout will be set, and a
131 normal watcher (with the persist flag set!) will be created.
132
133 This has the effect of timing out after the specified period of
134 inactivity has happened.
135
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.
101 140
102 my $w = EV::timer $after, $repeat, $callback 141 my $w = EV::timer $after, $repeat, $callback
103 my $w = EV::timer_ns $after, $repeat, $callback 142 my $w = EV::timer_ns $after, $repeat, $callback
104 Calls the callback after $after seconds. If $repeat is true, the 143 Calls the callback after $after seconds. If $repeat is true, the
105 timer will be restarted after the callback returns. This means that 144 timer will be restarted after the callback returns. This means that
… …
130 jumps. 169 jumps.
131 170
132 The "timer_abs_ns" variant doesn't add/start the newly created 171 The "timer_abs_ns" variant doesn't add/start the newly created
133 watcher. 172 watcher.
134 173
135 my $w = EV::signal $signum, $callback 174 my $w = EV::signal $signal, $callback
136 my $w = EV::signal_ns $signum, $callback 175 my $w = EV::signal_ns $signal, $callback
137 Call the callback when signal $signum is received. 176 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
178 watchers are persistent no natter what.
179
180 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
182 removes it again when you stop it. Pelr does the same when you
183 add/remove callbacks to %SIG, so watch out.
184
185 Unfortunately, only one handler can be registered per signal. Screw
186 libevent.
138 187
139 The "signal_ns" variant doesn't add/start the newly created watcher. 188 The "signal_ns" variant doesn't add/start the newly created watcher.
140 189
141THE EV::Event CLASS 190THE EV::Event CLASS
142 All EV functions creating an event watcher (designated by "my $w =" 191 All EV functions creating an event watcher (designated by "my $w ="
… …
159 $old_callback = $w->cb ($new_callback) 208 $old_callback = $w->cb ($new_callback)
160 Return the previously set callback and optionally set a new one. 209 Return the previously set callback and optionally set a new one.
161 210
162 $current_fh = $w->fh 211 $current_fh = $w->fh
163 $old_fh = $w->fh ($new_fh) 212 $old_fh = $w->fh ($new_fh)
164 Returns the previously set filehandle and optionally set a new one. 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
217 $old_signal = $w->signal ($new_signal)
218 Returns the previously set signal number and optionally set a new
219 one (also sets the EV::SIGNAL flag when setting a signal).
165 220
166 $current_eventmask = $w->events 221 $current_eventmask = $w->events
167 $old_eventmask = $w->events ($new_eventmask) 222 $old_eventmask = $w->events ($new_eventmask)
168 Returns the previously set event mask and optionally set a new one. 223 Returns the previously set event mask and optionally set a new one.
169 224

Diff Legend

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