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;
}

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

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