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

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

=cut

our $NPRI = 4;
our $BASE = init;
priority_init $NPRI;

1;

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

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