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

Comparing EV/EV.pm (file contents):
Revision 1.3 by root, Fri Oct 26 17:40:31 2007 UTC vs.
Revision 1.12 by root, Mon Oct 29 08:52:28 2007 UTC

… …
2 2
3EV - perl interface to libevent, monkey.org/~provos/libevent/ 3EV - perl interface to libevent, monkey.org/~provos/libevent/
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use EV; 7 use EV;
8 8
9 # TIMER 9 # TIMER
10 10
11 my $w = EV::timer 2, 0, sub { 11 my $w = EV::timer 2, 0, sub {
12 warn "is called after 2s"; 12 warn "is called after 2s";
13 }; 13 };
14 14
15 my $w = EV::timer 2, 1, sub { 15 my $w = EV::timer 2, 1, sub {
16 warn "is called roughly every 2s (repeat = 1)"; 16 warn "is called roughly every 2s (repeat = 1)";
17 }; 17 };
18 18
19 undef $w; # destroy event watcher again 19 undef $w; # destroy event watcher again
20 20
21 # IO
22
23 my $w = EV::timer_abs 0, 60, sub { 21 my $w = EV::timer_abs 0, 60, sub {
24 warn "is called every minute, on the minute, exactly"; 22 warn "is called every minute, on the minute, exactly";
25 }; 23 };
26 24
25 # IO
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);
36 36
37 my $w = EV::timed_io \*STDIN, EV::READ, 30, sub {
38 my ($w, $events) = @_;
39 if ($_[1] & EV::TIMEOUT) {
40 warn "nothing entered within 30 seconds, bye bye.\n";
41 $w->stop;
42 } else {
43 my $line = <STDIN>;
44 warn "you entered something, you again have 30 seconds.\n";
45 }
46 };
47
48 # SIGNALS
49
50 my $w = EV::signal 'QUIT', sub {
51 warn "sigquit received\n";
52 };
53
54 my $w = EV::signal 3, sub {
55 warn "sigquit received (this is GNU/Linux, right?)\n";
56 };
57
37 # MAINLOOP 58 # MAINLOOP
38 EV::dispatch; # loop as long as watchers are active 59 EV::dispatch; # loop as long as watchers are active
39 EV::loop; # the same thing 60 EV::loop; # the same thing
40 EV::loop EV::LOOP_ONCE; 61 EV::loop EV::LOOP_ONCE; # block until some events could be handles
41 EV::loop EV::LOOP_ONSHOT; 62 EV::loop EV::LOOP_NONBLOCK; # check and handle some events, but do not wait
42 63
43=head1 DESCRIPTION 64=head1 DESCRIPTION
44 65
45This module provides an interface to libevent 66This module provides an interface to libevent
46(L<http://monkey.org/~provos/libevent/>). 67(L<http://monkey.org/~provos/libevent/>). You probably should acquaint
68yourself with its documentation and source code to be able to use this
69module fully.
70
71Please note thta this module disables the libevent EPOLL method by
72default, see BUGS, below, if you need to enable it.
47 73
48=cut 74=cut
49 75
50package EV; 76package EV;
51 77
52use strict; 78use strict;
53 79
54BEGIN { 80BEGIN {
55 our $VERSION = '0.01'; 81 our $VERSION = '0.03';
56 use XSLoader; 82 use XSLoader;
57 XSLoader::load "EV", $VERSION; 83 XSLoader::load "EV", $VERSION;
58} 84}
59 85
60=head1 FUNCTIONAL INTERFACE 86=head1 BASIC INTERFACE
61 87
62=over 4 88=over 4
63 89
64=item $EV::NPRI 90=item $EV::NPRI
65 91
66How many priority levels are available. 92How many priority levels are available.
93
94=item $EV::DIED
95
96Must contain a reference to a function that is called when a callback
97throws an exception (with $@ containing thr error). The default prints an
98informative message and continues.
99
100If this callback throws an exception it will be silently ignored.
67 101
68=item $time = EV::now 102=item $time = EV::now
69 103
70Returns the time in (fractional) seconds since the epoch. 104Returns the time in (fractional) seconds since the epoch.
71 105
… …
96 130
97As long as the returned watcher object is alive, call the C<$callback> 131As long as the returned watcher object is alive, call the C<$callback>
98when the events specified in C<$eventmask> happen. Initially, the timeout 132when the events specified in C<$eventmask> happen. Initially, the timeout
99is disabled. 133is disabled.
100 134
101The C<io_ns> variant doesn't add/start the newly created watcher. 135You can additionall set a timeout to occur on the watcher, but note that
136this timeout will not be reset when you get an I/O event in the EV::PERSIST
137case, and reaching a timeout will always stop the watcher even in the
138EV::PERSIST case.
139
140If you want a timeout to occur only after a specific time of inactivity, set
141a repeating timeout and do NOT use EV::PERSIST.
102 142
103Eventmask can be one or more of these constants ORed together: 143Eventmask can be one or more of these constants ORed together:
104 144
105 EV::READ wait until read() wouldn't block anymore 145 EV::READ wait until read() wouldn't block anymore
106 EV::WRITE wait until write() wouldn't block anymore 146 EV::WRITE wait until write() wouldn't block anymore
107 EV::PERSIST stay active after an event occured 147 EV::PERSIST stay active after a (non-timeout) event occured
148
149The C<io_ns> variant doesn't add/start the newly created watcher.
150
151=item my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback
152
153=item my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback
154
155Same as C<io> and C<io_ns>, but also specifies a timeout (as if there was
156a call to C<< $w->timeout ($timout, 1) >>. The persist flag is not allowed
157and will automatically be cleared. The watcher will be restarted after each event.
158
159If the timeout is zero or undef, no timeout will be set, and a normal
160watcher (with the persist flag set!) will be created.
161
162This has the effect of timing out after the specified period of inactivity
163has happened.
164
165Due to the design of libevent, this is also relatively inefficient, having
166one or two io watchers and a separate timeout watcher that you reset on
167activity (by calling its C<start> method) is usually more efficient.
108 168
109=item my $w = EV::timer $after, $repeat, $callback 169=item my $w = EV::timer $after, $repeat, $callback
110 170
111=item my $w = EV::timer_ns $after, $repeat, $callback 171=item my $w = EV::timer_ns $after, $repeat, $callback
112 172
… …
133 193
134This can be used to schedule a callback to run at very regular intervals, 194This 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 195as long as the processing time is less then the interval (otherwise
136obviously events will be skipped). 196obviously events will be skipped).
137 197
198Another way to think about it (for the mathematically inclined) is that
199C<timer_abs> will try to tun the callback at the next possible time where
200C<$time = $at (mod $interval)>, regardless of any time jumps.
201
138The C<timer_abs_ns> variant doesn't add/start the newly created watcher. 202The C<timer_abs_ns> variant doesn't add/start the newly created watcher.
139 203
140=item my $w = EV::signal $signum, $callback 204=item my $w = EV::signal $signal, $callback
141 205
142=item my $w = EV::signal_ns $signum, $callback 206=item my $w = EV::signal_ns $signal, $callback
143 207
144Call the callback when signal $signum is received. 208Call the callback when $signal is received (the signal can be specified
209by number or by name, just as with kill or %SIG). Signal watchers are
210persistent no natter what.
211
212EV will grab the signal for the process (the kernel only allows one
213component to receive signals) when you start a signal watcher, and
214removes it again when you stop it. Pelr does the same when you add/remove
215callbacks to %SIG, so watch out.
216
217Unfortunately, only one handler can be registered per signal. Screw
218libevent.
145 219
146The C<signal_ns> variant doesn't add/start the newly created watcher. 220The C<signal_ns> variant doesn't add/start the newly created watcher.
147 221
148=back 222=back
149 223
… …
177 251
178=item $current_fh = $w->fh 252=item $current_fh = $w->fh
179 253
180=item $old_fh = $w->fh ($new_fh) 254=item $old_fh = $w->fh ($new_fh)
181 255
182Returns the previously set filehandle and optionally set a new one. 256Returns the previously set filehandle and optionally set a new one (also
257clears the EV::SIGNAL flag when setting a filehandle).
258
259=item $current_signal = $w->signal
260
261=item $old_signal = $w->signal ($new_signal)
262
263Returns the previously set signal number and optionally set a new one (also sets
264the EV::SIGNAL flag when setting a signal).
183 265
184=item $current_eventmask = $w->events 266=item $current_eventmask = $w->events
185 267
186=item $old_eventmask = $w->events ($new_eventmask) 268=item $old_eventmask = $w->events ($new_eventmask)
187 269
… …
204=head1 BUGS 286=head1 BUGS
205 287
206Lots. Libevent itself isn't well tested and rather buggy, and this module 288Lots. Libevent itself isn't well tested and rather buggy, and this module
207is quite new at the moment. 289is quite new at the moment.
208 290
291Please note that the epoll method is not, in general, reliable in programs
292that use fork (even if no libveent calls are being made in the forked
293process). If your program behaves erratically, try setting the environment
294variable C<EVENT_NOEPOLL> first when running the program.
295
296In general, if you fork, then you can only use the EV module in one of the
297children.
298
209=cut 299=cut
300
301our $DIED = sub {
302 warn "EV: error in callback (ignoring): $@";
303};
210 304
211our $NPRI = 4; 305our $NPRI = 4;
212our $BASE = init; 306our $BASE = init;
213priority_init $NPRI; 307priority_init $NPRI;
214 308
309push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
310
2151; 3111;
216 312
217=head1 SEE ALSO 313=head1 SEE ALSO
218 314
219 L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>. 315 L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
316 L<EV::AnyEvent>.
220 317
221=head1 AUTHOR 318=head1 AUTHOR
222 319
223 Marc Lehmann <schmorp@schmorp.de> 320 Marc Lehmann <schmorp@schmorp.de>
224 http://home.schmorp.de/ 321 http://home.schmorp.de/

Diff Legend

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