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

Comparing EV/README (file contents):
Revision 1.2 by root, Sat Oct 27 19:11:27 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 73
47 Please note thta this module disables the libevent EPOLL method by 74BASIC INTERFACE
48 default, see BUGS, below, if you need to enable it.
49
50FUNCTIONAL INTERFACE
51 $EV::NPRI 75 $EV::NPRI
52 How many priority levels are available. 76 How many priority levels are available.
77
78 $EV::DIED
79 Must contain a reference to a function that is called when a
80 callback throws an exception (with $@ containing thr error). The
81 default prints an informative message and continues.
82
83 If this callback throws an exception it will be silently ignored.
53 84
54 $time = EV::now 85 $time = EV::now
55 Returns the time in (fractional) seconds since the epoch. 86 Returns the time in (fractional) seconds since the epoch.
56 87
57 $version = EV::version 88 $version = EV::version
… …
74 my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback 105 my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
75 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
76 when the events specified in $eventmask happen. Initially, the 107 when the events specified in $eventmask happen. Initially, the
77 timeout is disabled. 108 timeout is disabled.
78 109
79 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
80 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
81 EV::PERSIST case, and reaching a timeout will always stop the 112 EV::PERSIST case, and reaching a timeout will always stop the
82 watcher even in the EV::PERSIST case. 113 watcher even in the EV::PERSIST case.
83 114
84 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
… …
89 EV::READ wait until read() wouldn't block anymore 120 EV::READ wait until read() wouldn't block anymore
90 EV::WRITE wait until write() wouldn't block anymore 121 EV::WRITE wait until write() wouldn't block anymore
91 EV::PERSIST stay active after a (non-timeout) event occured 122 EV::PERSIST stay active after a (non-timeout) event occured
92 123
93 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.
94 143
95 my $w = EV::timer $after, $repeat, $callback 144 my $w = EV::timer $after, $repeat, $callback
96 my $w = EV::timer_ns $after, $repeat, $callback 145 my $w = EV::timer_ns $after, $repeat, $callback
97 Calls the callback after $after seconds. If $repeat is true, the 146 Calls the callback after $after seconds. If $repeat is true, the
98 timer will be restarted after the callback returns. This means that 147 timer will be restarted after the callback returns. This means that
… …
123 jumps. 172 jumps.
124 173
125 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
126 watcher. 175 watcher.
127 176
128 my $w = EV::signal $signum, $callback 177 my $w = EV::signal $signal, $callback
129 my $w = EV::signal_ns $signum, $callback 178 my $w = EV::signal_ns $signal, $callback
130 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.
131 190
132 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.
133 192
134THE EV::Event CLASS 193THE EV::Event CLASS
135 All EV functions creating an event watcher (designated by "my $w =" 194 All EV functions creating an event watcher (designated by "my $w ="
… …
152 $old_callback = $w->cb ($new_callback) 211 $old_callback = $w->cb ($new_callback)
153 Return the previously set callback and optionally set a new one. 212 Return the previously set callback and optionally set a new one.
154 213
155 $current_fh = $w->fh 214 $current_fh = $w->fh
156 $old_fh = $w->fh ($new_fh) 215 $old_fh = $w->fh ($new_fh)
157 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).
158 223
159 $current_eventmask = $w->events 224 $current_eventmask = $w->events
160 $old_eventmask = $w->events ($new_eventmask) 225 $old_eventmask = $w->events ($new_eventmask)
161 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.
162 227
… …
168 233
169 $w->priority_set ($priority) 234 $w->priority_set ($priority)
170 Set the priority of the watcher to $priority (0 <= $priority < 235 Set the priority of the watcher to $priority (0 <= $priority <
171 $EV::NPRI). 236 $EV::NPRI).
172 237
173BUGS 238THREADS
174 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
175 module is quite new at the moment. 240 evil and must die.
176
177 Please note that the epoll method is not, in general, reliable in
178 programs that use fork (even if no libveent calls are being made in the
179 forked process). If your program behaves erratically, try setting the
180 environment variable "EVENT_NOEPOLL" first when running the program.
181
182 In general, if you fork, then you can only use the EV module in one of
183 the children.
184 241
185SEE ALSO 242SEE ALSO
186 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>.
187 L<EV::AnyEvent>. 244 L<EV::AnyEvent>.
188 245

Diff Legend

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