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
  
  my $w = EV::timer_abs 0, 60, sub {
     warn "is called every minute, on the minute, exactly";
  };
  
  # IO
  
  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);
  
  my $w = EV::timed_io \*STDIN, EV::READ, 30, sub {
     my ($w, $events) = @_;
     if ($_[1] & EV::TIMEOUT) {
        warn "nothing entered within 30 seconds, bye bye.\n";
        $w->stop;
     } else {
        my $line = <STDIN>;
        warn "you entered something, you again have 30 seconds.\n";
     }
  };
  
  # SIGNALS
  
  my $w = EV::signal 'QUIT', sub {
     warn "sigquit received\n";
  };
  
  my $w = EV::signal 3, sub {
     warn "sigquit received (this is GNU/Linux, right?)\n";
  };
  
  # MAINLOOP
  EV::dispatch; # loop as long as watchers are active
  EV::loop;     # the same thing
  EV::loop EV::LOOP_ONCE;     # block until some events could be handles
  EV::loop EV::LOOP_NONBLOCK; # check and handle some events, but do not wait

=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.03';
   use XSLoader;
   XSLoader::load "EV", $VERSION;
}

@EV::Io::ISA       = "EV::Watcher";
@EV::Time::ISA     = "EV::Watcher";
@EV::Timer::ISA    = "EV::Time";
@EV::Periodic::ISA = "EV::Time";
@EV::Signal::ISA   = "EV::Watcher";
@EV::Idle::ISA     = "EV::Watcher";
@EV::Prepare::ISA  = "EV::Watcher";
@EV::Check::ISA    = "EV::Watcher";

=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 $signal, $callback

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

Call the callback when $signal is received (the signal can be specified
by number or by name, just as with kill or %SIG). Signal watchers are
persistent no natter what.

EV will grab the signal for the process (the kernel only allows one
component to receive signals) when you start a signal watcher, and
removes it again when you stop it. Pelr does the same when you add/remove
callbacks to %SIG, so watch out.

Unfortunately, only one handler can be registered per signal. Screw
libevent.

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 THREADS

Threads are not supported by this in any way. Perl pseudo-threads is evil
and must die.

=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): $@";
};

init;

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.15
Committed:	Wed Oct 31 18:28:00 2007 UTC (16 years, 6 months ago) by root
Branch:	MAIN
Changes since 1.14:	+9 -0 lines
Log Message:	add prepare watcher
#	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	root	1.11	use EV;
8
9			# 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			my $w = EV::timer_abs 0, 60, sub {
22			warn "is called every minute, on the minute, exactly";
23			};
24
25			# IO
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			warn "nothing received on stdin for 10 seconds, retrying";
31			} else {
32			warn "stdin is readable, you entered: ", <STDIN>;
33			}
34			};
35			$w->timeout (10);
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
58			# MAINLOOP
59			EV::dispatch; # loop as long as watchers are active
60			EV::loop; # the same thing
61			EV::loop EV::LOOP_ONCE; # block until some events could be handles
62			EV::loop EV::LOOP_NONBLOCK; # check and handle some events, but do not wait
63	root	1.2
64	root	1.1	=head1 DESCRIPTION
65
66			This module provides an interface to libevent
67	root	1.6	(L<http://monkey.org/~provos/libevent/>). You probably should acquaint
68			yourself with its documentation and source code to be able to use this
69			module fully.
70
71			Please note thta this module disables the libevent EPOLL method by
72			default, see BUGS, below, if you need to enable it.
73	root	1.1
74			=cut
75
76			package EV;
77
78			use strict;
79
80			BEGIN {
81	root	1.12	our $VERSION = '0.03';
82	root	1.1	use XSLoader;
83			XSLoader::load "EV", $VERSION;
84			}
85
86	root	1.15	@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	root	1.8	=head1 BASIC INTERFACE
96	root	1.1
97			=over 4
98
99	root	1.2	=item $EV::NPRI
100
101			How many priority levels are available.
102
103	root	1.8	=item $EV::DIED
104
105			Must contain a reference to a function that is called when a callback
106			throws an exception (with $@ containing thr error). The default prints an
107			informative message and continues.
108
109			If this callback throws an exception it will be silently ignored.
110
111	root	1.2	=item $time = EV::now
112
113			Returns the time in (fractional) seconds since the epoch.
114
115			=item $version = EV::version
116
117			=item $method = EV::method
118
119			Return version string and event polling method used.
120
121			=item EV::loop $flags # EV::LOOP_ONCE, EV::LOOP_ONESHOT
122
123			=item EV::loopexit $after
124
125			Exit any active loop or dispatch after C<$after> seconds or immediately if
126			C<$after> is missing or zero.
127
128			=item EV::dispatch
129
130			Same as C<EV::loop 0>.
131
132			=item EV::event $callback
133
134			Creates a new event watcher waiting for nothing, calling the given callback.
135
136			=item my $w = EV::io $fileno_or_fh, $eventmask, $callback
137
138			=item my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
139
140			As long as the returned watcher object is alive, call the C<$callback>
141			when the events specified in C<$eventmask> happen. Initially, the timeout
142			is disabled.
143
144	root	1.10	You can additionall set a timeout to occur on the watcher, but note that
145	root	1.7	this timeout will not be reset when you get an I/O event in the EV::PERSIST
146			case, and reaching a timeout will always stop the watcher even in the
147			EV::PERSIST case.
148
149			If you want a timeout to occur only after a specific time of inactivity, set
150			a repeating timeout and do NOT use EV::PERSIST.
151	root	1.2
152			Eventmask can be one or more of these constants ORed together:
153
154			EV::READ wait until read() wouldn't block anymore
155			EV::WRITE wait until write() wouldn't block anymore
156	root	1.7	EV::PERSIST stay active after a (non-timeout) event occured
157
158			The C<io_ns> variant doesn't add/start the newly created watcher.
159	root	1.2
160	root	1.10	=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
164			Same as C<io> and C<io_ns>, but also specifies a timeout (as if there was
165			a call to C<< $w->timeout ($timout, 1) >>. The persist flag is not allowed
166			and will automatically be cleared. The watcher will be restarted after each event.
167
168			If the timeout is zero or undef, no timeout will be set, and a normal
169			watcher (with the persist flag set!) will be created.
170
171			This has the effect of timing out after the specified period of inactivity
172			has happened.
173
174			Due to the design of libevent, this is also relatively inefficient, having
175			one or two io watchers and a separate timeout watcher that you reset on
176			activity (by calling its C<start> method) is usually more efficient.
177
178	root	1.2	=item my $w = EV::timer $after, $repeat, $callback
179
180			=item my $w = EV::timer_ns $after, $repeat, $callback
181
182			Calls the callback after C<$after> seconds. If C<$repeat> is true, the
183			timer will be restarted after the callback returns. This means that the
184			callback would be called roughly every C<$after> seconds, prolonged by the
185			time the callback takes.
186
187			The C<timer_ns> variant doesn't add/start the newly created watcher.
188
189			=item my $w = EV::timer_abs $at, $interval, $callback
190
191			=item my $w = EV::timer_abs_ns $at, $interval, $callback
192
193			Similar to EV::timer, but the time is given as an absolute point in time
194			(C<$at>), plus an optional C<$interval>.
195
196			If the C<$interval> is zero, then the callback will be called at the time
197			C<$at> if that is in the future, or as soon as possible if its in the
198			past. It will not automatically repeat.
199
200			If the C<$interval> is nonzero, then the watcher will always be scheduled
201			to time out at the next C<$at + integer * $interval> time.
202
203			This can be used to schedule a callback to run at very regular intervals,
204			as long as the processing time is less then the interval (otherwise
205			obviously events will be skipped).
206
207	root	1.7	Another way to think about it (for the mathematically inclined) is that
208			C<timer_abs> will try to tun the callback at the next possible time where
209			C<$time = $at (mod $interval)>, regardless of any time jumps.
210
211	root	1.2	The C<timer_abs_ns> variant doesn't add/start the newly created watcher.
212
213	root	1.11	=item my $w = EV::signal $signal, $callback
214
215			=item my $w = EV::signal_ns $signal, $callback
216
217			Call the callback when $signal is received (the signal can be specified
218			by number or by name, just as with kill or %SIG). Signal watchers are
219			persistent no natter what.
220	root	1.2
221	root	1.11	EV will grab the signal for the process (the kernel only allows one
222			component to receive signals) when you start a signal watcher, and
223			removes it again when you stop it. Pelr does the same when you add/remove
224			callbacks to %SIG, so watch out.
225	root	1.2
226	root	1.11	Unfortunately, only one handler can be registered per signal. Screw
227			libevent.
228	root	1.2
229			The C<signal_ns> variant doesn't add/start the newly created watcher.
230
231	root	1.1	=back
232
233	root	1.2	=head1 THE EV::Event CLASS
234
235			All EV functions creating an event watcher (designated by C<my $w =>
236			above) support the following methods on the returned watcher object:
237
238			=over 4
239
240			=item $w->add ($timeout)
241
242			Stops and (re-)starts the event watcher, setting the optional timeout to
243			the given value, or clearing the timeout if none is given.
244
245			=item $w->start
246
247			Stops and (re-)starts the event watcher without touching the timeout.
248
249			=item $w->del
250
251			=item $w->stop
252	root	1.1
253	root	1.2	Stop the event watcher if it was started.
254	root	1.1
255	root	1.2	=item $current_callback = $w->cb
256	root	1.1
257	root	1.2	=item $old_callback = $w->cb ($new_callback)
258
259			Return the previously set callback and optionally set a new one.
260
261			=item $current_fh = $w->fh
262
263			=item $old_fh = $w->fh ($new_fh)
264
265	root	1.10	Returns the previously set filehandle and optionally set a new one (also
266			clears 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
272			Returns the previously set signal number and optionally set a new one (also sets
273			the EV::SIGNAL flag when setting a signal).
274	root	1.2
275			=item $current_eventmask = $w->events
276
277			=item $old_eventmask = $w->events ($new_eventmask)
278
279			Returns the previously set event mask and optionally set a new one.
280
281			=item $w->timeout ($after, $repeat)
282
283			Resets the timeout (see C<EV::timer> for details).
284
285			=item $w->timeout_abs ($at, $interval)
286
287			Resets the timeout (see C<EV::timer_abs> for details).
288
289			=item $w->priority_set ($priority)
290
291			Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).
292	root	1.1
293			=back
294
295	root	1.13	=head1 THREADS
296
297			Threads are not supported by this in any way. Perl pseudo-threads is evil
298			and must die.
299
300	root	1.1	=head1 BUGS
301
302	root	1.2	Lots. Libevent itself isn't well tested and rather buggy, and this module
303			is quite new at the moment.
304
305	root	1.7	Please note that the epoll method is not, in general, reliable in programs
306			that use fork (even if no libveent calls are being made in the forked
307			process). If your program behaves erratically, try setting the environment
308			variable C<EVENT_NOEPOLL> first when running the program.
309
310			In general, if you fork, then you can only use the EV module in one of the
311			children.
312	root	1.6
313	root	1.1	=cut
314
315	root	1.8	our $DIED = sub {
316			warn "EV: error in callback (ignoring): $@";
317			};
318
319	root	1.14	init;
320	root	1.1
321	root	1.4	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
322
323	root	1.1	1;
324
325	root	1.3	=head1 SEE ALSO
326
327			L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
328	root	1.5	L<EV::AnyEvent>.
329	root	1.3
330	root	1.1	=head1 AUTHOR
331
332			Marc Lehmann <schmorp@schmorp.de>
333			http://home.schmorp.de/
334
335			=cut
336