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 *
#	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/>).
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	=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	=back
149
150	=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
170	Stop the event watcher if it was started.
171
172	=item $current_callback = $w->cb
173
174	=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
202	=back
203
204	=head1 BUGS
205
206	Lots. Libevent itself isn't well tested and rather buggy, and this module
207	is quite new at the moment.
208
209	=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