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

Comparing EV/EV.pm (file contents):
Revision 1.7 by root, Sat Oct 27 14:54:20 2007 UTC vs.
Revision 1.14 by root, Wed Oct 31 10:53:53 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/>). You probably should acquaint 67(L<http://monkey.org/~provos/libevent/>). You probably should acquaint
… …
55package EV; 76package EV;
56 77
57use strict; 78use strict;
58 79
59BEGIN { 80BEGIN {
60 our $VERSION = '0.01'; 81 our $VERSION = '0.03';
61 use XSLoader; 82 use XSLoader;
62 XSLoader::load "EV", $VERSION; 83 XSLoader::load "EV", $VERSION;
63} 84}
64 85
65=head1 FUNCTIONAL INTERFACE 86=head1 BASIC INTERFACE
66 87
67=over 4 88=over 4
68 89
69=item $EV::NPRI 90=item $EV::NPRI
70 91
71How 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.
72 101
73=item $time = EV::now 102=item $time = EV::now
74 103
75Returns the time in (fractional) seconds since the epoch. 104Returns the time in (fractional) seconds since the epoch.
76 105
… …
101 130
102As 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>
103when the events specified in C<$eventmask> happen. Initially, the timeout 132when the events specified in C<$eventmask> happen. Initially, the timeout
104is disabled. 133is disabled.
105 134
106Youc an additionall set a timeout to occur on the watcher, but note that 135You can additionall set a timeout to occur on the watcher, but note that
107this timeout will not be reset when you get an I/O event in the EV::PERSIST 136this timeout will not be reset when you get an I/O event in the EV::PERSIST
108case, and reaching a timeout will always stop the watcher even in the 137case, and reaching a timeout will always stop the watcher even in the
109EV::PERSIST case. 138EV::PERSIST case.
110 139
111If you want a timeout to occur only after a specific time of inactivity, set 140If you want a timeout to occur only after a specific time of inactivity, set
… …
116 EV::READ wait until read() wouldn't block anymore 145 EV::READ wait until read() wouldn't block anymore
117 EV::WRITE wait until write() wouldn't block anymore 146 EV::WRITE wait until write() wouldn't block anymore
118 EV::PERSIST stay active after a (non-timeout) event occured 147 EV::PERSIST stay active after a (non-timeout) event occured
119 148
120The C<io_ns> variant doesn't add/start the newly created watcher. 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.
121 168
122=item my $w = EV::timer $after, $repeat, $callback 169=item my $w = EV::timer $after, $repeat, $callback
123 170
124=item my $w = EV::timer_ns $after, $repeat, $callback 171=item my $w = EV::timer_ns $after, $repeat, $callback
125 172
… …
152C<timer_abs> will try to tun the callback at the next possible time where 199C<timer_abs> will try to tun the callback at the next possible time where
153C<$time = $at (mod $interval)>, regardless of any time jumps. 200C<$time = $at (mod $interval)>, regardless of any time jumps.
154 201
155The 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.
156 203
157=item my $w = EV::signal $signum, $callback 204=item my $w = EV::signal $signal, $callback
158 205
159=item my $w = EV::signal_ns $signum, $callback 206=item my $w = EV::signal_ns $signal, $callback
160 207
161Call 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.
162 219
163The 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.
164 221
165=back 222=back
166 223
… …
194 251
195=item $current_fh = $w->fh 252=item $current_fh = $w->fh
196 253
197=item $old_fh = $w->fh ($new_fh) 254=item $old_fh = $w->fh ($new_fh)
198 255
199Returns 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).
200 265
201=item $current_eventmask = $w->events 266=item $current_eventmask = $w->events
202 267
203=item $old_eventmask = $w->events ($new_eventmask) 268=item $old_eventmask = $w->events ($new_eventmask)
204 269
… …
215=item $w->priority_set ($priority) 280=item $w->priority_set ($priority)
216 281
217Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI). 282Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).
218 283
219=back 284=back
285
286=head1 THREADS
287
288Threads are not supported by this in any way. Perl pseudo-threads is evil
289and must die.
220 290
221=head1 BUGS 291=head1 BUGS
222 292
223Lots. Libevent itself isn't well tested and rather buggy, and this module 293Lots. Libevent itself isn't well tested and rather buggy, and this module
224is quite new at the moment. 294is quite new at the moment.
… …
231In general, if you fork, then you can only use the EV module in one of the 301In general, if you fork, then you can only use the EV module in one of the
232children. 302children.
233 303
234=cut 304=cut
235 305
236our $NPRI = 4; 306our $DIED = sub {
237our $BASE = init; 307 warn "EV: error in callback (ignoring): $@";
238priority_init $NPRI; 308};
309
310init;
239 311
240push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"]; 312push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
241 313
2421; 3141;
243 315

Diff Legend

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