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 *
#	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			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	root	1.1	=back
154
155	root	1.2	=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	root	1.1
175	root	1.2	Stop the event watcher if it was started.
176	root	1.1
177	root	1.2	=item $current_callback = $w->cb
178	root	1.1
179	root	1.2	=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	root	1.1
207			=back
208
209			=head1 BUGS
210
211	root	1.2	Lots. Libevent itself isn't well tested and rather buggy, and this module
212			is quite new at the moment.
213
214	root	1.6	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	root	1.1	=cut
222
223			our $NPRI = 4;
224	root	1.6	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	root	1.1	priority_init $NPRI;
234
235	root	1.4	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
236
237	root	1.1	1;
238
239	root	1.3	=head1 SEE ALSO
240
241			L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
242	root	1.5	L<EV::AnyEvent>.
243	root	1.3
244	root	1.1	=head1 AUTHOR
245
246			Marc Lehmann <schmorp@schmorp.de>
247			http://home.schmorp.de/
248
249			=cut
250