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.17 by root, Wed Oct 31 21:34:45 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 = "EV::Watcher";
90@EV::Time::ISA = "EV::Watcher";
91@EV::Timer::ISA = "EV::Time";
92@EV::Periodic::ISA = "EV::Time";
93@EV::Signal::ISA = "EV::Watcher";
94@EV::Idle::ISA = "EV::Watcher";
95@EV::Prepare::ISA = "EV::Watcher";
96@EV::Check::ISA = "EV::Watcher";
97@EV::Child::ISA = "EV::Watcher";
98
99=head1 BASIC INTERFACE
61 100
62=over 4 101=over 4
63 102
64=item $EV::NPRI 103=item $EV::NPRI
65 104
66How many priority levels are available. 105How many priority levels are available.
106
107=item $EV::DIED
108
109Must contain a reference to a function that is called when a callback
110throws an exception (with $@ containing thr error). The default prints an
111informative message and continues.
112
113If this callback throws an exception it will be silently ignored.
67 114
68=item $time = EV::now 115=item $time = EV::now
69 116
70Returns the time in (fractional) seconds since the epoch. 117Returns the time in (fractional) seconds since the epoch.
71 118
… …
96 143
97As long as the returned watcher object is alive, call the C<$callback> 144As long as the returned watcher object is alive, call the C<$callback>
98when the events specified in C<$eventmask> happen. Initially, the timeout 145when the events specified in C<$eventmask> happen. Initially, the timeout
99is disabled. 146is disabled.
100 147
101The C<io_ns> variant doesn't add/start the newly created watcher. 148You can additionall set a timeout to occur on the watcher, but note that
149this timeout will not be reset when you get an I/O event in the EV::PERSIST
150case, and reaching a timeout will always stop the watcher even in the
151EV::PERSIST case.
152
153If you want a timeout to occur only after a specific time of inactivity, set
154a repeating timeout and do NOT use EV::PERSIST.
102 155
103Eventmask can be one or more of these constants ORed together: 156Eventmask can be one or more of these constants ORed together:
104 157
105 EV::READ wait until read() wouldn't block anymore 158 EV::READ wait until read() wouldn't block anymore
106 EV::WRITE wait until write() wouldn't block anymore 159 EV::WRITE wait until write() wouldn't block anymore
107 EV::PERSIST stay active after an event occured 160 EV::PERSIST stay active after a (non-timeout) event occured
161
162The C<io_ns> variant doesn't add/start the newly created watcher.
163
164=item my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback
165
166=item my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback
167
168Same as C<io> and C<io_ns>, but also specifies a timeout (as if there was
169a call to C<< $w->timeout ($timout, 1) >>. The persist flag is not allowed
170and will automatically be cleared. The watcher will be restarted after each event.
171
172If the timeout is zero or undef, no timeout will be set, and a normal
173watcher (with the persist flag set!) will be created.
174
175This has the effect of timing out after the specified period of inactivity
176has happened.
177
178Due to the design of libevent, this is also relatively inefficient, having
179one or two io watchers and a separate timeout watcher that you reset on
180activity (by calling its C<start> method) is usually more efficient.
108 181
109=item my $w = EV::timer $after, $repeat, $callback 182=item my $w = EV::timer $after, $repeat, $callback
110 183
111=item my $w = EV::timer_ns $after, $repeat, $callback 184=item my $w = EV::timer_ns $after, $repeat, $callback
112 185
… …
133 206
134This can be used to schedule a callback to run at very regular intervals, 207This 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 208as long as the processing time is less then the interval (otherwise
136obviously events will be skipped). 209obviously events will be skipped).
137 210
211Another way to think about it (for the mathematically inclined) is that
212C<timer_abs> will try to tun the callback at the next possible time where
213C<$time = $at (mod $interval)>, regardless of any time jumps.
214
138The C<timer_abs_ns> variant doesn't add/start the newly created watcher. 215The C<timer_abs_ns> variant doesn't add/start the newly created watcher.
139 216
140=item my $w = EV::signal $signum, $callback 217=item my $w = EV::signal $signal, $callback
141 218
142=item my $w = EV::signal_ns $signum, $callback 219=item my $w = EV::signal_ns $signal, $callback
143 220
144Call the callback when signal $signum is received. 221Call the callback when $signal is received (the signal can be specified
222by number or by name, just as with kill or %SIG). Signal watchers are
223persistent no natter what.
224
225EV will grab the signal for the process (the kernel only allows one
226component to receive signals) when you start a signal watcher, and
227removes it again when you stop it. Pelr does the same when you add/remove
228callbacks to %SIG, so watch out.
229
230Unfortunately, only one handler can be registered per signal. Screw
231libevent.
145 232
146The C<signal_ns> variant doesn't add/start the newly created watcher. 233The C<signal_ns> variant doesn't add/start the newly created watcher.
147 234
148=back 235=back
149 236
… …
177 264
178=item $current_fh = $w->fh 265=item $current_fh = $w->fh
179 266
180=item $old_fh = $w->fh ($new_fh) 267=item $old_fh = $w->fh ($new_fh)
181 268
182Returns the previously set filehandle and optionally set a new one. 269Returns the previously set filehandle and optionally set a new one (also
270clears the EV::SIGNAL flag when setting a filehandle).
271
272=item $current_signal = $w->signal
273
274=item $old_signal = $w->signal ($new_signal)
275
276Returns the previously set signal number and optionally set a new one (also sets
277the EV::SIGNAL flag when setting a signal).
183 278
184=item $current_eventmask = $w->events 279=item $current_eventmask = $w->events
185 280
186=item $old_eventmask = $w->events ($new_eventmask) 281=item $old_eventmask = $w->events ($new_eventmask)
187 282
… …
198=item $w->priority_set ($priority) 293=item $w->priority_set ($priority)
199 294
200Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI). 295Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).
201 296
202=back 297=back
298
299=head1 THREADS
300
301Threads are not supported by this in any way. Perl pseudo-threads is evil
302and must die.
203 303
204=head1 BUGS 304=head1 BUGS
205 305
206Lots. Libevent itself isn't well tested and rather buggy, and this module 306Lots. Libevent itself isn't well tested and rather buggy, and this module
207is quite new at the moment. 307is quite new at the moment.
208 308
309Please note that the epoll method is not, in general, reliable in programs
310that use fork (even if no libveent calls are being made in the forked
311process). If your program behaves erratically, try setting the environment
312variable C<EVENT_NOEPOLL> first when running the program.
313
314In general, if you fork, then you can only use the EV module in one of the
315children.
316
209=cut 317=cut
210 318
211our $NPRI = 4; 319our $DIED = sub {
212our $BASE = init; 320 warn "EV: error in callback (ignoring): $@";
213priority_init $NPRI; 321};
322
323init;
324
325push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
214 326
2151; 3271;
216 328
217=head1 SEE ALSO 329=head1 SEE ALSO
218 330
219 L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>. 331 L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
332 L<EV::AnyEvent>.
220 333
221=head1 AUTHOR 334=head1 AUTHOR
222 335
223 Marc Lehmann <schmorp@schmorp.de> 336 Marc Lehmann <schmorp@schmorp.de>
224 http://home.schmorp.de/ 337 http://home.schmorp.de/

Diff Legend

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