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.15 by root, Wed Oct 31 18:28:00 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@EV::Io::ISA = "EV::Watcher";
87@EV::Time::ISA = "EV::Watcher";
88@EV::Timer::ISA = "EV::Time";
89@EV::Periodic::ISA = "EV::Time";
90@EV::Signal::ISA = "EV::Watcher";
91@EV::Idle::ISA = "EV::Watcher";
92@EV::Prepare::ISA = "EV::Watcher";
93@EV::Check::ISA = "EV::Watcher";
94
95=head1 BASIC INTERFACE
66 96
67=over 4 97=over 4
68 98
69=item $EV::NPRI 99=item $EV::NPRI
70 100
71How many priority levels are available. 101How many priority levels are available.
102
103=item $EV::DIED
104
105Must contain a reference to a function that is called when a callback
106throws an exception (with $@ containing thr error). The default prints an
107informative message and continues.
108
109If this callback throws an exception it will be silently ignored.
72 110
73=item $time = EV::now 111=item $time = EV::now
74 112
75Returns the time in (fractional) seconds since the epoch. 113Returns the time in (fractional) seconds since the epoch.
76 114
… …
101 139
102As long as the returned watcher object is alive, call the C<$callback> 140As long as the returned watcher object is alive, call the C<$callback>
103when the events specified in C<$eventmask> happen. Initially, the timeout 141when the events specified in C<$eventmask> happen. Initially, the timeout
104is disabled. 142is disabled.
105 143
106Youc an additionall set a timeout to occur on the watcher, but note that 144You 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 145this 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 146case, and reaching a timeout will always stop the watcher even in the
109EV::PERSIST case. 147EV::PERSIST case.
110 148
111If you want a timeout to occur only after a specific time of inactivity, set 149If you want a timeout to occur only after a specific time of inactivity, set
… …
116 EV::READ wait until read() wouldn't block anymore 154 EV::READ wait until read() wouldn't block anymore
117 EV::WRITE wait until write() wouldn't block anymore 155 EV::WRITE wait until write() wouldn't block anymore
118 EV::PERSIST stay active after a (non-timeout) event occured 156 EV::PERSIST stay active after a (non-timeout) event occured
119 157
120The C<io_ns> variant doesn't add/start the newly created watcher. 158The C<io_ns> variant doesn't add/start the newly created watcher.
159
160=item my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback
161
162=item my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback
163
164Same as C<io> and C<io_ns>, but also specifies a timeout (as if there was
165a call to C<< $w->timeout ($timout, 1) >>. The persist flag is not allowed
166and will automatically be cleared. The watcher will be restarted after each event.
167
168If the timeout is zero or undef, no timeout will be set, and a normal
169watcher (with the persist flag set!) will be created.
170
171This has the effect of timing out after the specified period of inactivity
172has happened.
173
174Due to the design of libevent, this is also relatively inefficient, having
175one or two io watchers and a separate timeout watcher that you reset on
176activity (by calling its C<start> method) is usually more efficient.
121 177
122=item my $w = EV::timer $after, $repeat, $callback 178=item my $w = EV::timer $after, $repeat, $callback
123 179
124=item my $w = EV::timer_ns $after, $repeat, $callback 180=item my $w = EV::timer_ns $after, $repeat, $callback
125 181
… …
152C<timer_abs> will try to tun the callback at the next possible time where 208C<timer_abs> will try to tun the callback at the next possible time where
153C<$time = $at (mod $interval)>, regardless of any time jumps. 209C<$time = $at (mod $interval)>, regardless of any time jumps.
154 210
155The C<timer_abs_ns> variant doesn't add/start the newly created watcher. 211The C<timer_abs_ns> variant doesn't add/start the newly created watcher.
156 212
157=item my $w = EV::signal $signum, $callback 213=item my $w = EV::signal $signal, $callback
158 214
159=item my $w = EV::signal_ns $signum, $callback 215=item my $w = EV::signal_ns $signal, $callback
160 216
161Call the callback when signal $signum is received. 217Call the callback when $signal is received (the signal can be specified
218by number or by name, just as with kill or %SIG). Signal watchers are
219persistent no natter what.
220
221EV will grab the signal for the process (the kernel only allows one
222component to receive signals) when you start a signal watcher, and
223removes it again when you stop it. Pelr does the same when you add/remove
224callbacks to %SIG, so watch out.
225
226Unfortunately, only one handler can be registered per signal. Screw
227libevent.
162 228
163The C<signal_ns> variant doesn't add/start the newly created watcher. 229The C<signal_ns> variant doesn't add/start the newly created watcher.
164 230
165=back 231=back
166 232
… …
194 260
195=item $current_fh = $w->fh 261=item $current_fh = $w->fh
196 262
197=item $old_fh = $w->fh ($new_fh) 263=item $old_fh = $w->fh ($new_fh)
198 264
199Returns the previously set filehandle and optionally set a new one. 265Returns the previously set filehandle and optionally set a new one (also
266clears the EV::SIGNAL flag when setting a filehandle).
267
268=item $current_signal = $w->signal
269
270=item $old_signal = $w->signal ($new_signal)
271
272Returns the previously set signal number and optionally set a new one (also sets
273the EV::SIGNAL flag when setting a signal).
200 274
201=item $current_eventmask = $w->events 275=item $current_eventmask = $w->events
202 276
203=item $old_eventmask = $w->events ($new_eventmask) 277=item $old_eventmask = $w->events ($new_eventmask)
204 278
… …
215=item $w->priority_set ($priority) 289=item $w->priority_set ($priority)
216 290
217Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI). 291Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).
218 292
219=back 293=back
294
295=head1 THREADS
296
297Threads are not supported by this in any way. Perl pseudo-threads is evil
298and must die.
220 299
221=head1 BUGS 300=head1 BUGS
222 301
223Lots. Libevent itself isn't well tested and rather buggy, and this module 302Lots. Libevent itself isn't well tested and rather buggy, and this module
224is quite new at the moment. 303is quite new at the moment.
… …
231In general, if you fork, then you can only use the EV module in one of the 310In general, if you fork, then you can only use the EV module in one of the
232children. 311children.
233 312
234=cut 313=cut
235 314
236our $NPRI = 4; 315our $DIED = sub {
237our $BASE = init; 316 warn "EV: error in callback (ignoring): $@";
238priority_init $NPRI; 317};
318
319init;
239 320
240push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"]; 321push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
241 322
2421; 3231;
243 324

Diff Legend

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