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

Comparing EV/EV.pm (file contents):
Revision 1.5 by root, Fri Oct 26 19:25:00 2007 UTC vs.
Revision 1.10 by root, Mon Oct 29 07:24:37 2007 UTC

… …
25 }; 25 };
26 26
27 my $w = EV::io \*STDIN, EV::READ | EV::PERSIST, sub { 27 my $w = EV::io \*STDIN, EV::READ | EV::PERSIST, sub {
28 my ($w, $events) = @_; # all callbacks get the watcher object and event mask 28 my ($w, $events) = @_; # all callbacks get the watcher object and event mask
29 if ($events & EV::TIMEOUT) { 29 if ($events & EV::TIMEOUT) {
30 warn "nothign received on stdin for 10 seconds, retrying"; 30 warn "nothing received on stdin for 10 seconds, retrying";
31 } else { 31 } else {
32 warn "stdin is readable, you entered: ", <STDIN>; 32 warn "stdin is readable, you entered: ", <STDIN>;
33 } 33 }
34 }; 34 };
35 $w->timeout (10); 35 $w->timeout (10);
… …
41 EV::loop EV::LOOP_ONSHOT; 41 EV::loop EV::LOOP_ONSHOT;
42 42
43=head1 DESCRIPTION 43=head1 DESCRIPTION
44 44
45This module provides an interface to libevent 45This module provides an interface to libevent
46(L<http://monkey.org/~provos/libevent/>). 46(L<http://monkey.org/~provos/libevent/>). You probably should acquaint
47yourself with its documentation and source code to be able to use this
48module fully.
49
50Please note thta this module disables the libevent EPOLL method by
51default, see BUGS, below, if you need to enable it.
47 52
48=cut 53=cut
49 54
50package EV; 55package EV;
51 56
52use strict; 57use strict;
53 58
54BEGIN { 59BEGIN {
55 our $VERSION = '0.01'; 60 our $VERSION = '0.02';
56 use XSLoader; 61 use XSLoader;
57 XSLoader::load "EV", $VERSION; 62 XSLoader::load "EV", $VERSION;
58} 63}
59 64
60=head1 FUNCTIONAL INTERFACE 65=head1 BASIC INTERFACE
61 66
62=over 4 67=over 4
63 68
64=item $EV::NPRI 69=item $EV::NPRI
65 70
66How many priority levels are available. 71How many priority levels are available.
72
73=item $EV::DIED
74
75Must contain a reference to a function that is called when a callback
76throws an exception (with $@ containing thr error). The default prints an
77informative message and continues.
78
79If this callback throws an exception it will be silently ignored.
67 80
68=item $time = EV::now 81=item $time = EV::now
69 82
70Returns the time in (fractional) seconds since the epoch. 83Returns the time in (fractional) seconds since the epoch.
71 84
… …
96 109
97As long as the returned watcher object is alive, call the C<$callback> 110As long as the returned watcher object is alive, call the C<$callback>
98when the events specified in C<$eventmask> happen. Initially, the timeout 111when the events specified in C<$eventmask> happen. Initially, the timeout
99is disabled. 112is disabled.
100 113
101The C<io_ns> variant doesn't add/start the newly created watcher. 114You can additionall set a timeout to occur on the watcher, but note that
115this timeout will not be reset when you get an I/O event in the EV::PERSIST
116case, and reaching a timeout will always stop the watcher even in the
117EV::PERSIST case.
118
119If you want a timeout to occur only after a specific time of inactivity, set
120a repeating timeout and do NOT use EV::PERSIST.
102 121
103Eventmask can be one or more of these constants ORed together: 122Eventmask can be one or more of these constants ORed together:
104 123
105 EV::READ wait until read() wouldn't block anymore 124 EV::READ wait until read() wouldn't block anymore
106 EV::WRITE wait until write() wouldn't block anymore 125 EV::WRITE wait until write() wouldn't block anymore
107 EV::PERSIST stay active after an event occured 126 EV::PERSIST stay active after a (non-timeout) event occured
127
128The C<io_ns> variant doesn't add/start the newly created watcher.
129
130=item my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback
131
132=item my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback
133
134Same as C<io> and C<io_ns>, but also specifies a timeout (as if there was
135a call to C<< $w->timeout ($timout, 1) >>. The persist flag is not allowed
136and will automatically be cleared. The watcher will be restarted after each event.
137
138If the timeout is zero or undef, no timeout will be set, and a normal
139watcher (with the persist flag set!) will be created.
140
141This has the effect of timing out after the specified period of inactivity
142has happened.
143
144Due to the design of libevent, this is also relatively inefficient, having
145one or two io watchers and a separate timeout watcher that you reset on
146activity (by calling its C<start> method) is usually more efficient.
108 147
109=item my $w = EV::timer $after, $repeat, $callback 148=item my $w = EV::timer $after, $repeat, $callback
110 149
111=item my $w = EV::timer_ns $after, $repeat, $callback 150=item my $w = EV::timer_ns $after, $repeat, $callback
112 151
… …
133 172
134This can be used to schedule a callback to run at very regular intervals, 173This can be used to schedule a callback to run at very regular intervals,
135as long as the processing time is less then the interval (otherwise 174as long as the processing time is less then the interval (otherwise
136obviously events will be skipped). 175obviously events will be skipped).
137 176
177Another way to think about it (for the mathematically inclined) is that
178C<timer_abs> will try to tun the callback at the next possible time where
179C<$time = $at (mod $interval)>, regardless of any time jumps.
180
138The C<timer_abs_ns> variant doesn't add/start the newly created watcher. 181The C<timer_abs_ns> variant doesn't add/start the newly created watcher.
139 182
140=item my $w = EV::signal $signum, $callback 183=item my $w = EV::signal $signum, $callback
141 184
142=item my $w = EV::signal_ns $signum, $callback 185=item my $w = EV::signal_ns $signum, $callback
… …
177 220
178=item $current_fh = $w->fh 221=item $current_fh = $w->fh
179 222
180=item $old_fh = $w->fh ($new_fh) 223=item $old_fh = $w->fh ($new_fh)
181 224
182Returns the previously set filehandle and optionally set a new one. 225Returns the previously set filehandle and optionally set a new one (also
226clears the EV::SIGNAL flag when setting a filehandle).
227
228=item $current_signal = $w->signal
229
230=item $old_signal = $w->signal ($new_signal)
231
232Returns the previously set signal number and optionally set a new one (also sets
233the EV::SIGNAL flag when setting a signal).
183 234
184=item $current_eventmask = $w->events 235=item $current_eventmask = $w->events
185 236
186=item $old_eventmask = $w->events ($new_eventmask) 237=item $old_eventmask = $w->events ($new_eventmask)
187 238
… …
204=head1 BUGS 255=head1 BUGS
205 256
206Lots. Libevent itself isn't well tested and rather buggy, and this module 257Lots. Libevent itself isn't well tested and rather buggy, and this module
207is quite new at the moment. 258is quite new at the moment.
208 259
260Please note that the epoll method is not, in general, reliable in programs
261that use fork (even if no libveent calls are being made in the forked
262process). If your program behaves erratically, try setting the environment
263variable C<EVENT_NOEPOLL> first when running the program.
264
265In general, if you fork, then you can only use the EV module in one of the
266children.
267
209=cut 268=cut
269
270our $DIED = sub {
271 warn "EV: error in callback (ignoring): $@";
272};
210 273
211our $NPRI = 4; 274our $NPRI = 4;
212our $BASE = init; 275our $BASE = init;
213priority_init $NPRI; 276priority_init $NPRI;
214 277

Diff Legend

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