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.

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 $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.7
Committed:	Sat Oct 27 14:54:20 2007 UTC (16 years, 6 months ago) by root
Branch:	MAIN
Changes since 1.6:	+22 -17 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			our $VERSION = '0.01';
61			use XSLoader;
62			XSLoader::load "EV", $VERSION;
63			}
64
65			=head1 FUNCTIONAL INTERFACE
66
67			=over 4
68
69	root	1.2	=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	root	1.7	Youc an additionall set a timeout to occur on the watcher, but note that
107			this timeout will not be reset when you get an I/O event in the EV::PERSIST
108			case, and reaching a timeout will always stop the watcher even in the
109			EV::PERSIST case.
110
111			If you want a timeout to occur only after a specific time of inactivity, set
112			a repeating timeout and do NOT use EV::PERSIST.
113	root	1.2
114			Eventmask can be one or more of these constants ORed together:
115
116			EV::READ wait until read() wouldn't block anymore
117			EV::WRITE wait until write() wouldn't block anymore
118	root	1.7	EV::PERSIST stay active after a (non-timeout) event occured
119
120			The C<io_ns> variant doesn't add/start the newly created watcher.
121	root	1.2
122			=item my $w = EV::timer $after, $repeat, $callback
123
124			=item my $w = EV::timer_ns $after, $repeat, $callback
125
126			Calls the callback after C<$after> seconds. If C<$repeat> is true, the
127			timer will be restarted after the callback returns. This means that the
128			callback would be called roughly every C<$after> seconds, prolonged by the
129			time the callback takes.
130
131			The C<timer_ns> variant doesn't add/start the newly created watcher.
132
133			=item my $w = EV::timer_abs $at, $interval, $callback
134
135			=item my $w = EV::timer_abs_ns $at, $interval, $callback
136
137			Similar to EV::timer, but the time is given as an absolute point in time
138			(C<$at>), plus an optional C<$interval>.
139
140			If the C<$interval> is zero, then the callback will be called at the time
141			C<$at> if that is in the future, or as soon as possible if its in the
142			past. It will not automatically repeat.
143
144			If the C<$interval> is nonzero, then the watcher will always be scheduled
145			to time out at the next C<$at + integer * $interval> time.
146
147			This can be used to schedule a callback to run at very regular intervals,
148			as long as the processing time is less then the interval (otherwise
149			obviously events will be skipped).
150
151	root	1.7	Another way to think about it (for the mathematically inclined) is that
152			C<timer_abs> will try to tun the callback at the next possible time where
153			C<$time = $at (mod $interval)>, regardless of any time jumps.
154
155	root	1.2	The C<timer_abs_ns> variant doesn't add/start the newly created watcher.
156
157			=item my $w = EV::signal $signum, $callback
158
159			=item my $w = EV::signal_ns $signum, $callback
160
161			Call the callback when signal $signum is received.
162
163			The C<signal_ns> variant doesn't add/start the newly created watcher.
164
165	root	1.1	=back
166
167	root	1.2	=head1 THE EV::Event CLASS
168
169			All EV functions creating an event watcher (designated by C<my $w =>
170			above) support the following methods on the returned watcher object:
171
172			=over 4
173
174			=item $w->add ($timeout)
175
176			Stops and (re-)starts the event watcher, setting the optional timeout to
177			the given value, or clearing the timeout if none is given.
178
179			=item $w->start
180
181			Stops and (re-)starts the event watcher without touching the timeout.
182
183			=item $w->del
184
185			=item $w->stop
186	root	1.1
187	root	1.2	Stop the event watcher if it was started.
188	root	1.1
189	root	1.2	=item $current_callback = $w->cb
190	root	1.1
191	root	1.2	=item $old_callback = $w->cb ($new_callback)
192
193			Return the previously set callback and optionally set a new one.
194
195			=item $current_fh = $w->fh
196
197			=item $old_fh = $w->fh ($new_fh)
198
199			Returns the previously set filehandle and optionally set a new one.
200
201			=item $current_eventmask = $w->events
202
203			=item $old_eventmask = $w->events ($new_eventmask)
204
205			Returns the previously set event mask and optionally set a new one.
206
207			=item $w->timeout ($after, $repeat)
208
209			Resets the timeout (see C<EV::timer> for details).
210
211			=item $w->timeout_abs ($at, $interval)
212
213			Resets the timeout (see C<EV::timer_abs> for details).
214
215			=item $w->priority_set ($priority)
216
217			Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).
218	root	1.1
219			=back
220
221			=head1 BUGS
222
223	root	1.2	Lots. Libevent itself isn't well tested and rather buggy, and this module
224			is quite new at the moment.
225
226	root	1.7	Please note that the epoll method is not, in general, reliable in programs
227			that use fork (even if no libveent calls are being made in the forked
228			process). If your program behaves erratically, try setting the environment
229			variable C<EVENT_NOEPOLL> first when running the program.
230
231			In general, if you fork, then you can only use the EV module in one of the
232			children.
233	root	1.6
234	root	1.1	=cut
235
236			our $NPRI = 4;
237	root	1.7	our $BASE = init;
238	root	1.1	priority_init $NPRI;
239
240	root	1.4	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
241
242	root	1.1	1;
243
244	root	1.3	=head1 SEE ALSO
245
246			L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
247	root	1.5	L<EV::AnyEvent>.
248	root	1.3
249	root	1.1	=head1 AUTHOR
250
251			Marc Lehmann <schmorp@schmorp.de>
252			http://home.schmorp.de/
253
254			=cut
255