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 "nothign 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.

Youc an 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::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.

=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.9
Committed:	Sun Oct 28 06:40:46 2007 UTC (16 years, 6 months ago) by root
Branch:	MAIN
CVS Tags:	rel-0_02
Changes since 1.8:	+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			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			warn "nothign 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			# 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.7	Youc an additionall set a timeout to occur on the watcher, but note that
115			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			=item my $w = EV::timer $after, $repeat, $callback
131
132			=item my $w = EV::timer_ns $after, $repeat, $callback
133
134			Calls the callback after C<$after> seconds. If C<$repeat> is true, the
135			timer will be restarted after the callback returns. This means that the
136			callback would be called roughly every C<$after> seconds, prolonged by the
137			time the callback takes.
138
139			The C<timer_ns> variant doesn't add/start the newly created watcher.
140
141			=item my $w = EV::timer_abs $at, $interval, $callback
142
143			=item my $w = EV::timer_abs_ns $at, $interval, $callback
144
145			Similar to EV::timer, but the time is given as an absolute point in time
146			(C<$at>), plus an optional C<$interval>.
147
148			If the C<$interval> is zero, then the callback will be called at the time
149			C<$at> if that is in the future, or as soon as possible if its in the
150			past. It will not automatically repeat.
151
152			If the C<$interval> is nonzero, then the watcher will always be scheduled
153			to time out at the next C<$at + integer * $interval> time.
154
155			This can be used to schedule a callback to run at very regular intervals,
156			as long as the processing time is less then the interval (otherwise
157			obviously events will be skipped).
158
159	root	1.7	Another way to think about it (for the mathematically inclined) is that
160			C<timer_abs> will try to tun the callback at the next possible time where
161			C<$time = $at (mod $interval)>, regardless of any time jumps.
162
163	root	1.2	The C<timer_abs_ns> variant doesn't add/start the newly created watcher.
164
165			=item my $w = EV::signal $signum, $callback
166
167			=item my $w = EV::signal_ns $signum, $callback
168
169			Call the callback when signal $signum is received.
170
171			The C<signal_ns> variant doesn't add/start the newly created watcher.
172
173	root	1.1	=back
174
175	root	1.2	=head1 THE EV::Event CLASS
176
177			All EV functions creating an event watcher (designated by C<my $w =>
178			above) support the following methods on the returned watcher object:
179
180			=over 4
181
182			=item $w->add ($timeout)
183
184			Stops and (re-)starts the event watcher, setting the optional timeout to
185			the given value, or clearing the timeout if none is given.
186
187			=item $w->start
188
189			Stops and (re-)starts the event watcher without touching the timeout.
190
191			=item $w->del
192
193			=item $w->stop
194	root	1.1
195	root	1.2	Stop the event watcher if it was started.
196	root	1.1
197	root	1.2	=item $current_callback = $w->cb
198	root	1.1
199	root	1.2	=item $old_callback = $w->cb ($new_callback)
200
201			Return the previously set callback and optionally set a new one.
202
203			=item $current_fh = $w->fh
204
205			=item $old_fh = $w->fh ($new_fh)
206
207			Returns the previously set filehandle and optionally set a new one.
208
209			=item $current_eventmask = $w->events
210
211			=item $old_eventmask = $w->events ($new_eventmask)
212
213			Returns the previously set event mask and optionally set a new one.
214
215			=item $w->timeout ($after, $repeat)
216
217			Resets the timeout (see C<EV::timer> for details).
218
219			=item $w->timeout_abs ($at, $interval)
220
221			Resets the timeout (see C<EV::timer_abs> for details).
222
223			=item $w->priority_set ($priority)
224
225			Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).
226	root	1.1
227			=back
228
229			=head1 BUGS
230
231	root	1.2	Lots. Libevent itself isn't well tested and rather buggy, and this module
232			is quite new at the moment.
233
234	root	1.7	Please note that the epoll method is not, in general, reliable in programs
235			that use fork (even if no libveent calls are being made in the forked
236			process). If your program behaves erratically, try setting the environment
237			variable C<EVENT_NOEPOLL> first when running the program.
238
239			In general, if you fork, then you can only use the EV module in one of the
240			children.
241	root	1.6
242	root	1.1	=cut
243
244	root	1.8	our $DIED = sub {
245			warn "EV: error in callback (ignoring): $@";
246			};
247
248	root	1.1	our $NPRI = 4;
249	root	1.7	our $BASE = init;
250	root	1.1	priority_init $NPRI;
251
252	root	1.4	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
253
254	root	1.1	1;
255
256	root	1.3	=head1 SEE ALSO
257
258			L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
259	root	1.5	L<EV::AnyEvent>.
260	root	1.3
261	root	1.1	=head1 AUTHOR
262
263			Marc Lehmann <schmorp@schmorp.de>
264			http://home.schmorp.de/
265
266			=cut
267