EV/EV.pm

=head1 NAME

EV - perl interface to libevent, monkey.org/~provos/libevent/

=head1 SYNOPSIS

 use EV;

 # TIMER

 my $w = EV::timer 2, 0, sub {
    warn "is called after 2s";
 };

 my $w = EV::timer 2, 1, sub {
    warn "is called roughly every 2s (repeat = 1)";
 };

 undef $w; # destroy event watcher again

 # IO

 my $w = EV::timer_abs 0, 60, sub {
    warn "is called every minute, on the minute, exactly";
 };

 my $w = EV::io \*STDIN, EV::READ | EV::PERSIST, sub {
    my ($w, $events) = @_; # all callbacks get the watcher object and event mask
    if ($events & EV::TIMEOUT) {
       warn "nothing received on stdin for 10 seconds, retrying";
    } else {
       warn "stdin is readable, you entered: ", <STDIN>;
    }
 };
 $w->timeout (10);

 # MAINLOOP
 EV::dispatch; # loop as long as watchers are active
 EV::loop;     # the same thing
 EV::loop EV::LOOP_ONCE;
 EV::loop EV::LOOP_ONSHOT;

=head1 DESCRIPTION

This module provides an interface to libevent
(L<http://monkey.org/~provos/libevent/>). You probably should acquaint
yourself with its documentation and source code to be able to use this
module fully.

Please note thta this module disables the libevent EPOLL method by
default, see BUGS, below, if you need to enable it.

=cut

package EV;

use strict;

BEGIN {
   our $VERSION = '0.02';
   use XSLoader;
   XSLoader::load "EV", $VERSION;
}

=head1 BASIC INTERFACE

=over 4

=item $EV::NPRI

How many priority levels are available.

=item $EV::DIED

Must contain a reference to a function that is called when a callback
throws an exception (with $@ containing thr error). The default prints an
informative message and continues.

If this callback throws an exception it will be silently ignored.

=item $time = EV::now

Returns the time in (fractional) seconds since the epoch.

=item $version = EV::version

=item $method = EV::method

Return version string and event polling method used.

=item EV::loop $flags  # EV::LOOP_ONCE, EV::LOOP_ONESHOT

=item EV::loopexit $after

Exit any active loop or dispatch after C<$after> seconds or immediately if
C<$after> is missing or zero.

=item EV::dispatch

Same as C<EV::loop 0>.

=item EV::event $callback

Creates a new event watcher waiting for nothing, calling the given callback.

=item my $w = EV::io $fileno_or_fh, $eventmask, $callback

=item my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback

As long as the returned watcher object is alive, call the C<$callback>
when the events specified in C<$eventmask> happen. Initially, the timeout
is disabled.

You can additionall set a timeout to occur on the watcher, but note that
this timeout will not be reset when you get an I/O event in the EV::PERSIST
case, and reaching a timeout will always stop the watcher even in the
EV::PERSIST case.

If you want a timeout to occur only after a specific time of inactivity, set
a repeating timeout and do NOT use EV::PERSIST.

Eventmask can be one or more of these constants ORed together:

  EV::READ     wait until read() wouldn't block anymore
  EV::WRITE    wait until write() wouldn't block anymore
  EV::PERSIST  stay active after a (non-timeout) event occured

The C<io_ns> variant doesn't add/start the newly created watcher.

=item my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback

=item my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback

Same as C<io> and C<io_ns>, but also specifies a timeout (as if there was
a call to C<< $w->timeout ($timout, 1) >>. The persist flag is not allowed
and will automatically be cleared. The watcher will be restarted after each event.

If the timeout is zero or undef, no timeout will be set, and a normal
watcher (with the persist flag set!) will be created.

This has the effect of timing out after the specified period of inactivity
has happened.

Due to the design of libevent, this is also relatively inefficient, having
one or two io watchers and a separate timeout watcher that you reset on
activity (by calling its C<start> method) is usually more efficient.

=item my $w = EV::timer $after, $repeat, $callback

=item my $w = EV::timer_ns $after, $repeat, $callback

Calls the callback after C<$after> seconds. If C<$repeat> is true, the
timer will be restarted after the callback returns. This means that the
callback would be called roughly every C<$after> seconds, prolonged by the
time the callback takes.

The C<timer_ns> variant doesn't add/start the newly created watcher.

=item my $w = EV::timer_abs $at, $interval, $callback

=item my $w = EV::timer_abs_ns $at, $interval, $callback

Similar to EV::timer, but the time is given as an absolute point in time
(C<$at>), plus an optional C<$interval>.

If the C<$interval> is zero, then the callback will be called at the time
C<$at> if that is in the future, or as soon as possible if its in the
past. It will not automatically repeat.

If the C<$interval> is nonzero, then the watcher will always be scheduled
to time out at the next C<$at + integer * $interval> time.

This can be used to schedule a callback to run at very regular intervals,
as long as the processing time is less then the interval (otherwise
obviously events will be skipped).

Another way to think about it (for the mathematically inclined) is that
C<timer_abs> will try to tun the callback at the next possible time where
C<$time = $at (mod $interval)>, regardless of any time jumps.

The C<timer_abs_ns> variant doesn't add/start the newly created watcher.

=item my $w = EV::signal $signum, $callback

=item my $w = EV::signal_ns $signum, $callback

Call the callback when signal $signum is received.

The C<signal_ns> variant doesn't add/start the newly created watcher.

=back

=head1 THE EV::Event CLASS

All EV functions creating an event watcher (designated by C<my $w =>
above) support the following methods on the returned watcher object:

=over 4

=item $w->add ($timeout)

Stops and (re-)starts the event watcher, setting the optional timeout to
the given value, or clearing the timeout if none is given.

=item $w->start

Stops and (re-)starts the event watcher without touching the timeout.

=item $w->del

=item $w->stop

Stop the event watcher if it was started.

=item $current_callback = $w->cb

=item $old_callback = $w->cb ($new_callback)

Return the previously set callback and optionally set a new one.

=item $current_fh = $w->fh

=item $old_fh = $w->fh ($new_fh)

Returns the previously set filehandle and optionally set a new one (also
clears the EV::SIGNAL flag when setting a filehandle).

=item $current_signal = $w->signal

=item $old_signal = $w->signal ($new_signal)

Returns the previously set signal number and optionally set a new one (also sets
the EV::SIGNAL flag when setting a signal).

=item $current_eventmask = $w->events

=item $old_eventmask = $w->events ($new_eventmask)

Returns the previously set event mask and optionally set a new one.

=item $w->timeout ($after, $repeat)

Resets the timeout (see C<EV::timer> for details).

=item $w->timeout_abs ($at, $interval)

Resets the timeout (see C<EV::timer_abs> for details).

=item $w->priority_set ($priority)

Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).

=back

=head1 BUGS

Lots. Libevent itself isn't well tested and rather buggy, and this module
is quite new at the moment.

Please note that the epoll method is not, in general, reliable in programs
that use fork (even if no libveent calls are being made in the forked
process). If your program behaves erratically, try setting the environment
variable C<EVENT_NOEPOLL> first when running the program.

In general, if you fork, then you can only use the EV module in one of the
children.

=cut

our $DIED = sub {
   warn "EV: error in callback (ignoring): $@";
};

our $NPRI = 4;
our $BASE = init;
priority_init $NPRI;

push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];

1;

=head1 SEE ALSO

  L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
  L<EV::AnyEvent>.

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

Revision:	1.10
Committed:	Mon Oct 29 07:24:37 2007 UTC (16 years, 6 months ago) by root
Branch:	MAIN
Changes since 1.9:	+29 -3 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			EV - perl interface to libevent, monkey.org/~provos/libevent/
4
5			=head1 SYNOPSIS
6
7			use EV;
8
9	root	1.2	# TIMER
10
11			my $w = EV::timer 2, 0, sub {
12			warn "is called after 2s";
13			};
14
15			my $w = EV::timer 2, 1, sub {
16			warn "is called roughly every 2s (repeat = 1)";
17			};
18
19			undef $w; # destroy event watcher again
20
21			# IO
22
23			my $w = EV::timer_abs 0, 60, sub {
24			warn "is called every minute, on the minute, exactly";
25			};
26
27			my $w = EV::io \*STDIN, EV::READ \| EV::PERSIST, sub {
28			my ($w, $events) = @_; # all callbacks get the watcher object and event mask
29			if ($events & EV::TIMEOUT) {
30	root	1.10	warn "nothing received on stdin for 10 seconds, retrying";
31	root	1.2	} else {
32			warn "stdin is readable, you entered: ", <STDIN>;
33			}
34			};
35			$w->timeout (10);
36
37			# MAINLOOP
38			EV::dispatch; # loop as long as watchers are active
39			EV::loop; # the same thing
40			EV::loop EV::LOOP_ONCE;
41			EV::loop EV::LOOP_ONSHOT;
42
43	root	1.1	=head1 DESCRIPTION
44
45			This module provides an interface to libevent
46	root	1.6	(L<http://monkey.org/~provos/libevent/>). You probably should acquaint
47			yourself with its documentation and source code to be able to use this
48			module fully.
49
50			Please note thta this module disables the libevent EPOLL method by
51			default, see BUGS, below, if you need to enable it.
52	root	1.1
53			=cut
54
55			package EV;
56
57			use strict;
58
59			BEGIN {
60	root	1.9	our $VERSION = '0.02';
61	root	1.1	use XSLoader;
62			XSLoader::load "EV", $VERSION;
63			}
64
65	root	1.8	=head1 BASIC INTERFACE
66	root	1.1
67			=over 4
68
69	root	1.2	=item $EV::NPRI
70
71			How many priority levels are available.
72
73	root	1.8	=item $EV::DIED
74
75			Must contain a reference to a function that is called when a callback
76			throws an exception (with $@ containing thr error). The default prints an
77			informative message and continues.
78
79			If this callback throws an exception it will be silently ignored.
80
81	root	1.2	=item $time = EV::now
82
83			Returns the time in (fractional) seconds since the epoch.
84
85			=item $version = EV::version
86
87			=item $method = EV::method
88
89			Return version string and event polling method used.
90
91			=item EV::loop $flags # EV::LOOP_ONCE, EV::LOOP_ONESHOT
92
93			=item EV::loopexit $after
94
95			Exit any active loop or dispatch after C<$after> seconds or immediately if
96			C<$after> is missing or zero.
97
98			=item EV::dispatch
99
100			Same as C<EV::loop 0>.
101
102			=item EV::event $callback
103
104			Creates a new event watcher waiting for nothing, calling the given callback.
105
106			=item my $w = EV::io $fileno_or_fh, $eventmask, $callback
107
108			=item my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
109
110			As long as the returned watcher object is alive, call the C<$callback>
111			when the events specified in C<$eventmask> happen. Initially, the timeout
112			is disabled.
113
114	root	1.10	You can additionall set a timeout to occur on the watcher, but note that
115	root	1.7	this timeout will not be reset when you get an I/O event in the EV::PERSIST
116			case, and reaching a timeout will always stop the watcher even in the
117			EV::PERSIST case.
118
119			If you want a timeout to occur only after a specific time of inactivity, set
120			a repeating timeout and do NOT use EV::PERSIST.
121	root	1.2
122			Eventmask can be one or more of these constants ORed together:
123
124			EV::READ wait until read() wouldn't block anymore
125			EV::WRITE wait until write() wouldn't block anymore
126	root	1.7	EV::PERSIST stay active after a (non-timeout) event occured
127
128			The C<io_ns> variant doesn't add/start the newly created watcher.
129	root	1.2
130	root	1.10	=item my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback
131
132			=item my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback
133
134			Same as C<io> and C<io_ns>, but also specifies a timeout (as if there was
135			a call to C<< $w->timeout ($timout, 1) >>. The persist flag is not allowed
136			and will automatically be cleared. The watcher will be restarted after each event.
137
138			If the timeout is zero or undef, no timeout will be set, and a normal
139			watcher (with the persist flag set!) will be created.
140
141			This has the effect of timing out after the specified period of inactivity
142			has happened.
143
144			Due to the design of libevent, this is also relatively inefficient, having
145			one or two io watchers and a separate timeout watcher that you reset on
146			activity (by calling its C<start> method) is usually more efficient.
147
148	root	1.2	=item my $w = EV::timer $after, $repeat, $callback
149
150			=item my $w = EV::timer_ns $after, $repeat, $callback
151
152			Calls the callback after C<$after> seconds. If C<$repeat> is true, the
153			timer will be restarted after the callback returns. This means that the
154			callback would be called roughly every C<$after> seconds, prolonged by the
155			time the callback takes.
156
157			The C<timer_ns> variant doesn't add/start the newly created watcher.
158
159			=item my $w = EV::timer_abs $at, $interval, $callback
160
161			=item my $w = EV::timer_abs_ns $at, $interval, $callback
162
163			Similar to EV::timer, but the time is given as an absolute point in time
164			(C<$at>), plus an optional C<$interval>.
165
166			If the C<$interval> is zero, then the callback will be called at the time
167			C<$at> if that is in the future, or as soon as possible if its in the
168			past. It will not automatically repeat.
169
170			If the C<$interval> is nonzero, then the watcher will always be scheduled
171			to time out at the next C<$at + integer * $interval> time.
172
173			This can be used to schedule a callback to run at very regular intervals,
174			as long as the processing time is less then the interval (otherwise
175			obviously events will be skipped).
176
177	root	1.7	Another way to think about it (for the mathematically inclined) is that
178			C<timer_abs> will try to tun the callback at the next possible time where
179			C<$time = $at (mod $interval)>, regardless of any time jumps.
180
181	root	1.2	The C<timer_abs_ns> variant doesn't add/start the newly created watcher.
182
183			=item my $w = EV::signal $signum, $callback
184
185			=item my $w = EV::signal_ns $signum, $callback
186
187			Call the callback when signal $signum is received.
188
189			The C<signal_ns> variant doesn't add/start the newly created watcher.
190
191	root	1.1	=back
192
193	root	1.2	=head1 THE EV::Event CLASS
194
195			All EV functions creating an event watcher (designated by C<my $w =>
196			above) support the following methods on the returned watcher object:
197
198			=over 4
199
200			=item $w->add ($timeout)
201
202			Stops and (re-)starts the event watcher, setting the optional timeout to
203			the given value, or clearing the timeout if none is given.
204
205			=item $w->start
206
207			Stops and (re-)starts the event watcher without touching the timeout.
208
209			=item $w->del
210
211			=item $w->stop
212	root	1.1
213	root	1.2	Stop the event watcher if it was started.
214	root	1.1
215	root	1.2	=item $current_callback = $w->cb
216	root	1.1
217	root	1.2	=item $old_callback = $w->cb ($new_callback)
218
219			Return the previously set callback and optionally set a new one.
220
221			=item $current_fh = $w->fh
222
223			=item $old_fh = $w->fh ($new_fh)
224
225	root	1.10	Returns the previously set filehandle and optionally set a new one (also
226			clears the EV::SIGNAL flag when setting a filehandle).
227
228			=item $current_signal = $w->signal
229
230			=item $old_signal = $w->signal ($new_signal)
231
232			Returns the previously set signal number and optionally set a new one (also sets
233			the EV::SIGNAL flag when setting a signal).
234	root	1.2
235			=item $current_eventmask = $w->events
236
237			=item $old_eventmask = $w->events ($new_eventmask)
238
239			Returns the previously set event mask and optionally set a new one.
240
241			=item $w->timeout ($after, $repeat)
242
243			Resets the timeout (see C<EV::timer> for details).
244
245			=item $w->timeout_abs ($at, $interval)
246
247			Resets the timeout (see C<EV::timer_abs> for details).
248
249			=item $w->priority_set ($priority)
250
251			Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).
252	root	1.1
253			=back
254
255			=head1 BUGS
256
257	root	1.2	Lots. Libevent itself isn't well tested and rather buggy, and this module
258			is quite new at the moment.
259
260	root	1.7	Please note that the epoll method is not, in general, reliable in programs
261			that use fork (even if no libveent calls are being made in the forked
262			process). If your program behaves erratically, try setting the environment
263			variable C<EVENT_NOEPOLL> first when running the program.
264
265			In general, if you fork, then you can only use the EV module in one of the
266			children.
267	root	1.6
268	root	1.1	=cut
269
270	root	1.8	our $DIED = sub {
271			warn "EV: error in callback (ignoring): $@";
272			};
273
274	root	1.1	our $NPRI = 4;
275	root	1.7	our $BASE = init;
276	root	1.1	priority_init $NPRI;
277
278	root	1.4	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
279
280	root	1.1	1;
281
282	root	1.3	=head1 SEE ALSO
283
284			L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
285	root	1.5	L<EV::AnyEvent>.
286	root	1.3
287	root	1.1	=head1 AUTHOR
288
289			Marc Lehmann <schmorp@schmorp.de>
290			http://home.schmorp.de/
291
292			=cut
293