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

=head1 FUNCTIONAL INTERFACE

=over 4

=item $EV::NPRI

How many priority levels are available.

=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.

The C<io_ns> variant doesn't add/start the newly created watcher.

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 an event occured

=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).

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). Since this is such a common issue, this module will
force the epoll method in EV to be off *unless* the global variable
$EV::ENABLE_EPOLL is set to 1 *before* loading this module for the first
time.

=cut

our $NPRI = 4;
our $BASE;
our $ENABLE_EPOLL;

{
   local $ENV{EVENT_NOEPOLL};
   $ENV{EVENT_NOEPOLL} = 1 unless $ENABLE_EPOLL;
   $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.6
Committed:	Sat Oct 27 07:30:10 2007 UTC (16 years, 6 months ago) by root
Branch:	MAIN
Changes since 1.5:	+22 -2 lines
Log Message:	* empty log message *
#	Content
1	=head1 NAME
2
3	EV - perl interface to libevent, monkey.org/~provos/libevent/
4
5	=head1 SYNOPSIS
6
7	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	# 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	=head1 DESCRIPTION
44
45	This module provides an interface to libevent
46	(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
53	=cut
54
55	package EV;
56
57	use strict;
58
59	BEGIN {
60	our $VERSION = '0.01';
61	use XSLoader;
62	XSLoader::load "EV", $VERSION;
63	}
64
65	=head1 FUNCTIONAL INTERFACE
66
67	=over 4
68
69	=item $EV::NPRI
70
71	How many priority levels are available.
72
73	=item $time = EV::now
74
75	Returns the time in (fractional) seconds since the epoch.
76
77	=item $version = EV::version
78
79	=item $method = EV::method
80
81	Return version string and event polling method used.
82
83	=item EV::loop $flags # EV::LOOP_ONCE, EV::LOOP_ONESHOT
84
85	=item EV::loopexit $after
86
87	Exit any active loop or dispatch after C<$after> seconds or immediately if
88	C<$after> is missing or zero.
89
90	=item EV::dispatch
91
92	Same as C<EV::loop 0>.
93
94	=item EV::event $callback
95
96	Creates a new event watcher waiting for nothing, calling the given callback.
97
98	=item my $w = EV::io $fileno_or_fh, $eventmask, $callback
99
100	=item my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
101
102	As long as the returned watcher object is alive, call the C<$callback>
103	when the events specified in C<$eventmask> happen. Initially, the timeout
104	is disabled.
105
106	The C<io_ns> variant doesn't add/start the newly created watcher.
107
108	Eventmask can be one or more of these constants ORed together:
109
110	EV::READ wait until read() wouldn't block anymore
111	EV::WRITE wait until write() wouldn't block anymore
112	EV::PERSIST stay active after an event occured
113
114	=item my $w = EV::timer $after, $repeat, $callback
115
116	=item my $w = EV::timer_ns $after, $repeat, $callback
117
118	Calls the callback after C<$after> seconds. If C<$repeat> is true, the
119	timer will be restarted after the callback returns. This means that the
120	callback would be called roughly every C<$after> seconds, prolonged by the
121	time the callback takes.
122
123	The C<timer_ns> variant doesn't add/start the newly created watcher.
124
125	=item my $w = EV::timer_abs $at, $interval, $callback
126
127	=item my $w = EV::timer_abs_ns $at, $interval, $callback
128
129	Similar to EV::timer, but the time is given as an absolute point in time
130	(C<$at>), plus an optional C<$interval>.
131
132	If the C<$interval> is zero, then the callback will be called at the time
133	C<$at> if that is in the future, or as soon as possible if its in the
134	past. It will not automatically repeat.
135
136	If the C<$interval> is nonzero, then the watcher will always be scheduled
137	to time out at the next C<$at + integer * $interval> time.
138
139	This can be used to schedule a callback to run at very regular intervals,
140	as long as the processing time is less then the interval (otherwise
141	obviously events will be skipped).
142
143	The C<timer_abs_ns> variant doesn't add/start the newly created watcher.
144
145	=item my $w = EV::signal $signum, $callback
146
147	=item my $w = EV::signal_ns $signum, $callback
148
149	Call the callback when signal $signum is received.
150
151	The C<signal_ns> variant doesn't add/start the newly created watcher.
152
153	=back
154
155	=head1 THE EV::Event CLASS
156
157	All EV functions creating an event watcher (designated by C<my $w =>
158	above) support the following methods on the returned watcher object:
159
160	=over 4
161
162	=item $w->add ($timeout)
163
164	Stops and (re-)starts the event watcher, setting the optional timeout to
165	the given value, or clearing the timeout if none is given.
166
167	=item $w->start
168
169	Stops and (re-)starts the event watcher without touching the timeout.
170
171	=item $w->del
172
173	=item $w->stop
174
175	Stop the event watcher if it was started.
176
177	=item $current_callback = $w->cb
178
179	=item $old_callback = $w->cb ($new_callback)
180
181	Return the previously set callback and optionally set a new one.
182
183	=item $current_fh = $w->fh
184
185	=item $old_fh = $w->fh ($new_fh)
186
187	Returns the previously set filehandle and optionally set a new one.
188
189	=item $current_eventmask = $w->events
190
191	=item $old_eventmask = $w->events ($new_eventmask)
192
193	Returns the previously set event mask and optionally set a new one.
194
195	=item $w->timeout ($after, $repeat)
196
197	Resets the timeout (see C<EV::timer> for details).
198
199	=item $w->timeout_abs ($at, $interval)
200
201	Resets the timeout (see C<EV::timer_abs> for details).
202
203	=item $w->priority_set ($priority)
204
205	Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).
206
207	=back
208
209	=head1 BUGS
210
211	Lots. Libevent itself isn't well tested and rather buggy, and this module
212	is quite new at the moment.
213
214	Please note that the epoll method is not, in general, reliable in
215	programs that use fork (even if no libveent calls are being made in the
216	forked process). Since this is such a common issue, this module will
217	force the epoll method in EV to be off unless the global variable
218	$EV::ENABLE_EPOLL is set to 1 before loading this module for the first
219	time.
220
221	=cut
222
223	our $NPRI = 4;
224	our $BASE;
225	our $ENABLE_EPOLL;
226
227	{
228	local $ENV{EVENT_NOEPOLL};
229	$ENV{EVENT_NOEPOLL} = 1 unless $ENABLE_EPOLL;
230	$BASE = init;
231	}
232
233	priority_init $NPRI;
234
235	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
236
237	1;
238
239	=head1 SEE ALSO
240
241	L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
242	L<EV::AnyEvent>.
243
244	=head1 AUTHOR
245
246	Marc Lehmann <schmorp@schmorp.de>
247	http://home.schmorp.de/
248
249	=cut
250