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, $revents) = @_; # all callbacks get the watcher object and event mask
     if ($revents & 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, $revents) = @_;
     if ($revents & 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";
  };

  # CHILD/PID STATUS CHANGES

  my $w = EV::child 666, sub {
     my ($w, $revents, $status) = @_;
  };
  
  # MAINLOOP
  EV::dispatch; # loop as long as watchers are active
  EV::loop;     # the same thing
  EV::loop EV::LOOP_ONESHOT;  # 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 libev
(L<http://software.schmorp.de/pkg/libev.html>). You probably should
acquaint yourself with its documentation and source code to be able to use
this module fully.

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