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.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
45 module fully. 66 module fully.
46 67
47 Please note thta this module disables the libevent EPOLL method by 68 Please note thta this module disables the libevent EPOLL method by
48 default, see BUGS, below, if you need to enable it. 69 default, see BUGS, below, if you need to enable it.
49 70
50FUNCTIONAL INTERFACE 71BASIC INTERFACE
51 $EV::NPRI 72 $EV::NPRI
52 How many priority levels are available. 73 How many priority levels are available.
74
75 $EV::DIED
76 Must contain a reference to a function that is called when a
77 callback throws an exception (with $@ containing thr error). The
78 default prints an informative message and continues.
79
80 If this callback throws an exception it will be silently ignored.
53 81
54 $time = EV::now 82 $time = EV::now
55 Returns the time in (fractional) seconds since the epoch. 83 Returns the time in (fractional) seconds since the epoch.
56 84
57 $version = EV::version 85 $version = EV::version
… …
74 my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback 102 my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
75 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
76 when the events specified in $eventmask happen. Initially, the 104 when the events specified in $eventmask happen. Initially, the
77 timeout is disabled. 105 timeout is disabled.
78 106
79 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
80 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
81 EV::PERSIST case, and reaching a timeout will always stop the 109 EV::PERSIST case, and reaching a timeout will always stop the
82 watcher even in the EV::PERSIST case. 110 watcher even in the EV::PERSIST case.
83 111
84 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
… …
89 EV::READ wait until read() wouldn't block anymore 117 EV::READ wait until read() wouldn't block anymore
90 EV::WRITE wait until write() wouldn't block anymore 118 EV::WRITE wait until write() wouldn't block anymore
91 EV::PERSIST stay active after a (non-timeout) event occured 119 EV::PERSIST stay active after a (non-timeout) event occured
92 120
93 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.
94 140
95 my $w = EV::timer $after, $repeat, $callback 141 my $w = EV::timer $after, $repeat, $callback
96 my $w = EV::timer_ns $after, $repeat, $callback 142 my $w = EV::timer_ns $after, $repeat, $callback
97 Calls the callback after $after seconds. If $repeat is true, the 143 Calls the callback after $after seconds. If $repeat is true, the
98 timer will be restarted after the callback returns. This means that 144 timer will be restarted after the callback returns. This means that
… …
123 jumps. 169 jumps.
124 170
125 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
126 watcher. 172 watcher.
127 173
128 my $w = EV::signal $signum, $callback 174 my $w = EV::signal $signal, $callback
129 my $w = EV::signal_ns $signum, $callback 175 my $w = EV::signal_ns $signal, $callback
130 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.
131 187
132 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.
133 189
134THE EV::Event CLASS 190THE EV::Event CLASS
135 All EV functions creating an event watcher (designated by "my $w =" 191 All EV functions creating an event watcher (designated by "my $w ="
… …
152 $old_callback = $w->cb ($new_callback) 208 $old_callback = $w->cb ($new_callback)
153 Return the previously set callback and optionally set a new one. 209 Return the previously set callback and optionally set a new one.
154 210
155 $current_fh = $w->fh 211 $current_fh = $w->fh
156 $old_fh = $w->fh ($new_fh) 212 $old_fh = $w->fh ($new_fh)
157 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).
158 220
159 $current_eventmask = $w->events 221 $current_eventmask = $w->events
160 $old_eventmask = $w->events ($new_eventmask) 222 $old_eventmask = $w->events ($new_eventmask)
161 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.
162 224

Diff Legend

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