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

@EV::Io::ISA       =
@EV::Timer::ISA    =
@EV::Periodic::ISA =
@EV::Signal::ISA   =
@EV::Idle::ISA     =
@EV::Prepare::ISA  =
@EV::Check::ISA    =
@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.

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