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.5 by root, Thu Nov 1 13:33:12 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, $revents) = @_; # all callbacks get the watcher object and event mask
27 if ($events & EV::TIMEOUT) { 27 if ($revents & 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
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 };
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 };
34 55
56 # CHILD/PID STATUS CHANGES
57
58 my $w = EV::child 666, sub {
59 my ($w, $revents, $status) = @_;
60 };
61
35 # MAINLOOP 62 # MAINLOOP
36 EV::dispatch; # loop as long as watchers are active 63 EV::dispatch; # loop as long as watchers are active
37 EV::loop; # the same thing 64 EV::loop; # the same thing
38 EV::loop EV::LOOP_ONCE; 65 EV::loop EV::LOOP_ONESHOT; # block until some events could be handles
39 EV::loop EV::LOOP_ONSHOT; 66 EV::loop EV::LOOP_NONBLOCK; # check and handle some events, but do not wait
40 67
41DESCRIPTION 68DESCRIPTION
42 This module provides an interface to libevent 69 This module provides an interface to libev
43 (<http://monkey.org/~provos/libevent/>). You probably should acquaint 70 (<http://software.schmorp.de/pkg/libev.html>). You probably should
44 yourself with its documentation and source code to be able to use this 71 acquaint yourself with its documentation and source code to be able to
45 module fully. 72 use this 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 73
50BASIC INTERFACE 74BASIC INTERFACE
51 $EV::NPRI 75 $EV::NPRI
52 How many priority levels are available. 76 How many priority levels are available.
53 77
81 my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback 105 my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
82 As long as the returned watcher object is alive, call the $callback 106 As long as the returned watcher object is alive, call the $callback
83 when the events specified in $eventmask happen. Initially, the 107 when the events specified in $eventmask happen. Initially, the
84 timeout is disabled. 108 timeout is disabled.
85 109
86 Youc an additionall set a timeout to occur on the watcher, but note 110 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 111 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 112 EV::PERSIST case, and reaching a timeout will always stop the
89 watcher even in the EV::PERSIST case. 113 watcher even in the EV::PERSIST case.
90 114
91 If you want a timeout to occur only after a specific time of 115 If you want a timeout to occur only after a specific time of
96 EV::READ wait until read() wouldn't block anymore 120 EV::READ wait until read() wouldn't block anymore
97 EV::WRITE wait until write() wouldn't block anymore 121 EV::WRITE wait until write() wouldn't block anymore
98 EV::PERSIST stay active after a (non-timeout) event occured 122 EV::PERSIST stay active after a (non-timeout) event occured
99 123
100 The "io_ns" variant doesn't add/start the newly created watcher. 124 The "io_ns" variant doesn't add/start the newly created watcher.
125
126 my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback
127 my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback
128 Same as "io" and "io_ns", but also specifies a timeout (as if there
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
133 If the timeout is zero or undef, no timeout will be set, and a
134 normal watcher (with the persist flag set!) will be created.
135
136 This has the effect of timing out after the specified period of
137 inactivity has happened.
138
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.
101 143
102 my $w = EV::timer $after, $repeat, $callback 144 my $w = EV::timer $after, $repeat, $callback
103 my $w = EV::timer_ns $after, $repeat, $callback 145 my $w = EV::timer_ns $after, $repeat, $callback
104 Calls the callback after $after seconds. If $repeat is true, the 146 Calls the callback after $after seconds. If $repeat is true, the
105 timer will be restarted after the callback returns. This means that 147 timer will be restarted after the callback returns. This means that
130 jumps. 172 jumps.
131 173
132 The "timer_abs_ns" variant doesn't add/start the newly created 174 The "timer_abs_ns" variant doesn't add/start the newly created
133 watcher. 175 watcher.
134 176
135 my $w = EV::signal $signum, $callback 177 my $w = EV::signal $signal, $callback
136 my $w = EV::signal_ns $signum, $callback 178 my $w = EV::signal_ns $signal, $callback
137 Call the callback when signal $signum is received. 179 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
181 watchers are persistent no natter what.
182
183 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
185 removes it again when you stop it. Pelr does the same when you
186 add/remove callbacks to %SIG, so watch out.
187
188 Unfortunately, only one handler can be registered per signal. Screw
189 libevent.
138 190
139 The "signal_ns" variant doesn't add/start the newly created watcher. 191 The "signal_ns" variant doesn't add/start the newly created watcher.
140 192
141THE EV::Event CLASS 193THE EV::Event CLASS
142 All EV functions creating an event watcher (designated by "my $w =" 194 All EV functions creating an event watcher (designated by "my $w ="
159 $old_callback = $w->cb ($new_callback) 211 $old_callback = $w->cb ($new_callback)
160 Return the previously set callback and optionally set a new one. 212 Return the previously set callback and optionally set a new one.
161 213
162 $current_fh = $w->fh 214 $current_fh = $w->fh
163 $old_fh = $w->fh ($new_fh) 215 $old_fh = $w->fh ($new_fh)
164 Returns the previously set filehandle and optionally set a new one. 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
220 $old_signal = $w->signal ($new_signal)
221 Returns the previously set signal number and optionally set a new
222 one (also sets the EV::SIGNAL flag when setting a signal).
165 223
166 $current_eventmask = $w->events 224 $current_eventmask = $w->events
167 $old_eventmask = $w->events ($new_eventmask) 225 $old_eventmask = $w->events ($new_eventmask)
168 Returns the previously set event mask and optionally set a new one. 226 Returns the previously set event mask and optionally set a new one.
169 227
175 233
176 $w->priority_set ($priority) 234 $w->priority_set ($priority)
177 Set the priority of the watcher to $priority (0 <= $priority < 235 Set the priority of the watcher to $priority (0 <= $priority <
178 $EV::NPRI). 236 $EV::NPRI).
179 237
180BUGS 238THREADS
181 Lots. Libevent itself isn't well tested and rather buggy, and this 239 Threads are not supported by this in any way. Perl pseudo-threads is
182 module is quite new at the moment. 240 evil and must die.
183
184 Please note that the epoll method is not, in general, reliable in
185 programs that use fork (even if no libveent calls are being made in the
186 forked process). If your program behaves erratically, try setting the
187 environment variable "EVENT_NOEPOLL" first when running the program.
188
189 In general, if you fork, then you can only use the EV module in one of
190 the children.
191 241
192SEE ALSO 242SEE ALSO
193 L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>. 243 L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
194 L<EV::AnyEvent>. 244 L<EV::AnyEvent>.
195 245

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines