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

Comparing EV/EV.pm (file contents):
Revision 1.2 by root, Fri Oct 26 17:24:17 2007 UTC vs.
Revision 1.18 by root, Thu Nov 1 08:10:03 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, $revents) = @_; # all callbacks get the watcher object and event mask
29 if ($events & EV::TIMEOUT) { 29 if ($revents & 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
37 my $w = EV::timed_io \*STDIN, EV::READ, 30, sub {
38 my ($w, $revents) = @_;
39 if ($revents & 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 };
36 57
58 # CHILD/PID STATUS CHANGES
59
60 my $w = EV::child 666, sub {
61 my ($w, $revents, $status) = @_;
62 };
63
37 # MAINLOOP 64 # MAINLOOP
38 EV::dispatch; # loop as long as watchers are active 65 EV::dispatch; # loop as long as watchers are active
39 EV::loop; # the same thing 66 EV::loop; # the same thing
40 EV::loop EV::LOOP_ONCE; 67 EV::loop EV::LOOP_ONESHOT; # block until some events could be handles
41 EV::loop EV::LOOP_ONSHOT; 68 EV::loop EV::LOOP_NONBLOCK; # check and handle some events, but do not wait
42 69
43=head1 DESCRIPTION 70=head1 DESCRIPTION
44 71
45This module provides an interface to libevent 72This module provides an interface to libev
46(L<http://monkey.org/~provos/libevent/>). 73(L<http://software.schmorp.de/pkg/libev.html>). You probably should
74acquaint yourself with its documentation and source code to be able to use
75this module fully.
47 76
48=cut 77=cut
49 78
50package EV; 79package EV;
51 80
52use strict; 81use strict;
53 82
54BEGIN { 83BEGIN {
55 our $VERSION = '0.01'; 84 our $VERSION = '0.03';
56 use XSLoader; 85 use XSLoader;
57 XSLoader::load "EV", $VERSION; 86 XSLoader::load "EV", $VERSION;
58} 87}
59 88
60=head1 FUNCTIONAL INTERFACE 89@EV::Io::ISA =
90@EV::Timer::ISA =
91@EV::Periodic::ISA =
92@EV::Signal::ISA =
93@EV::Idle::ISA =
94@EV::Prepare::ISA =
95@EV::Check::ISA =
96@EV::Child::ISA = "EV::Watcher";
97
98=head1 BASIC INTERFACE
61 99
62=over 4 100=over 4
63 101
64=item $EV::NPRI 102=item $EV::NPRI
65 103
66How many priority levels are available. 104How many priority levels are available.
105
106=item $EV::DIED
107
108Must contain a reference to a function that is called when a callback
109throws an exception (with $@ containing thr error). The default prints an
110informative message and continues.
111
112If this callback throws an exception it will be silently ignored.
67 113
68=item $time = EV::now 114=item $time = EV::now
69 115
70Returns the time in (fractional) seconds since the epoch. 116Returns the time in (fractional) seconds since the epoch.
71 117
… …
96 142
97As long as the returned watcher object is alive, call the C<$callback> 143As long as the returned watcher object is alive, call the C<$callback>
98when the events specified in C<$eventmask> happen. Initially, the timeout 144when the events specified in C<$eventmask> happen. Initially, the timeout
99is disabled. 145is disabled.
100 146
101The C<io_ns> variant doesn't add/start the newly created watcher. 147You can additionall set a timeout to occur on the watcher, but note that
148this timeout will not be reset when you get an I/O event in the EV::PERSIST
149case, and reaching a timeout will always stop the watcher even in the
150EV::PERSIST case.
151
152If you want a timeout to occur only after a specific time of inactivity, set
153a repeating timeout and do NOT use EV::PERSIST.
102 154
103Eventmask can be one or more of these constants ORed together: 155Eventmask can be one or more of these constants ORed together:
104 156
105 EV::READ wait until read() wouldn't block anymore 157 EV::READ wait until read() wouldn't block anymore
106 EV::WRITE wait until write() wouldn't block anymore 158 EV::WRITE wait until write() wouldn't block anymore
107 EV::PERSIST stay active after an event occured 159 EV::PERSIST stay active after a (non-timeout) event occured
160
161The C<io_ns> variant doesn't add/start the newly created watcher.
162
163=item my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback
164
165=item my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback
166
167Same as C<io> and C<io_ns>, but also specifies a timeout (as if there was
168a call to C<< $w->timeout ($timout, 1) >>. The persist flag is not allowed
169and will automatically be cleared. The watcher will be restarted after each event.
170
171If the timeout is zero or undef, no timeout will be set, and a normal
172watcher (with the persist flag set!) will be created.
173
174This has the effect of timing out after the specified period of inactivity
175has happened.
176
177Due to the design of libevent, this is also relatively inefficient, having
178one or two io watchers and a separate timeout watcher that you reset on
179activity (by calling its C<start> method) is usually more efficient.
108 180
109=item my $w = EV::timer $after, $repeat, $callback 181=item my $w = EV::timer $after, $repeat, $callback
110 182
111=item my $w = EV::timer_ns $after, $repeat, $callback 183=item my $w = EV::timer_ns $after, $repeat, $callback
112 184
… …
133 205
134This can be used to schedule a callback to run at very regular intervals, 206This 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 207as long as the processing time is less then the interval (otherwise
136obviously events will be skipped). 208obviously events will be skipped).
137 209
210Another way to think about it (for the mathematically inclined) is that
211C<timer_abs> will try to tun the callback at the next possible time where
212C<$time = $at (mod $interval)>, regardless of any time jumps.
213
138The C<timer_abs_ns> variant doesn't add/start the newly created watcher. 214The C<timer_abs_ns> variant doesn't add/start the newly created watcher.
139 215
140=item my $w = EV::signal $signum, $callback 216=item my $w = EV::signal $signal, $callback
141 217
142=item my $w = EV::signal_ns $signum, $callback 218=item my $w = EV::signal_ns $signal, $callback
143 219
144Call the callback when signal $signum is received. 220Call the callback when $signal is received (the signal can be specified
221by number or by name, just as with kill or %SIG). Signal watchers are
222persistent no natter what.
223
224EV will grab the signal for the process (the kernel only allows one
225component to receive signals) when you start a signal watcher, and
226removes it again when you stop it. Pelr does the same when you add/remove
227callbacks to %SIG, so watch out.
228
229Unfortunately, only one handler can be registered per signal. Screw
230libevent.
145 231
146The C<signal_ns> variant doesn't add/start the newly created watcher. 232The C<signal_ns> variant doesn't add/start the newly created watcher.
147 233
148=back 234=back
149 235
… …
177 263
178=item $current_fh = $w->fh 264=item $current_fh = $w->fh
179 265
180=item $old_fh = $w->fh ($new_fh) 266=item $old_fh = $w->fh ($new_fh)
181 267
182Returns the previously set filehandle and optionally set a new one. 268Returns the previously set filehandle and optionally set a new one (also
269clears the EV::SIGNAL flag when setting a filehandle).
270
271=item $current_signal = $w->signal
272
273=item $old_signal = $w->signal ($new_signal)
274
275Returns the previously set signal number and optionally set a new one (also sets
276the EV::SIGNAL flag when setting a signal).
183 277
184=item $current_eventmask = $w->events 278=item $current_eventmask = $w->events
185 279
186=item $old_eventmask = $w->events ($new_eventmask) 280=item $old_eventmask = $w->events ($new_eventmask)
187 281
… …
199 293
200Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI). 294Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).
201 295
202=back 296=back
203 297
204=head1 BUGS 298=head1 THREADS
205 299
206Lots. Libevent itself isn't well tested and rather buggy, and this module 300Threads are not supported by this in any way. Perl pseudo-threads is evil
207is quite new at the moment. 301and must die.
208 302
209=cut 303=cut
210 304
211our $NPRI = 4; 305our $DIED = sub {
212our $BASE = init; 306 warn "EV: error in callback (ignoring): $@";
213priority_init $NPRI; 307};
308
309init;
310
311push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
214 312
2151; 3131;
314
315=head1 SEE ALSO
316
317 L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
318 L<EV::AnyEvent>.
216 319
217=head1 AUTHOR 320=head1 AUTHOR
218 321
219 Marc Lehmann <schmorp@schmorp.de> 322 Marc Lehmann <schmorp@schmorp.de>
220 http://home.schmorp.de/ 323 http://home.schmorp.de/

Diff Legend

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