[ViewVC] Diff of: cvs/EV/EV.pm

Comparing EV/EV.pm (file contents):
Revision 1.7 by root, Sat Oct 27 14:54:20 2007 UTC vs.
Revision 1.22 by root, Fri Nov 2 11:02:22 2007 UTC

1	=head1 NAME	1	=head1 NAME
2		2
3	EV - perl interface to libevent, monkey.org/~provos/libevent/	3	EV - perl interface to libev, a high performance full-featured event loop
4		4
5	=head1 SYNOPSIS	5	=head1 SYNOPSIS
6		6
7	use EV;	7	use EV;
8		8
9	# TIMER	9	# TIMERS
10		10
11	my $w = EV::timer 2, 0, sub {	11	my $w = EV::timer 2, 0, sub {
12	warn "is called after 2s";	12	warn "is called after 2s";
13	};	13	};
14		14
15	my $w = EV::timer 2, 1, sub {	15	my $w = EV::timer 2, 1, sub {
16	warn "is called roughly every 2s (repeat = 1)";	16	warn "is called roughly every 2s (repeat = 1)";
17	};	17	};
18		18
19	undef $w; # destroy event watcher again	19	undef $w; # destroy event watcher again
20		20
21	# IO
22
23	my $w = EV::timer_abs 0, 60, sub {	21	my $w = EV::periodic 0, 60, sub {
24	warn "is called every minute, on the minute, exactly";	22	warn "is called every minute, on the minute, exactly";
25	};	23	};
26		24
		25	# IO
		26
27	my $w = EV::io \*STDIN, EV::READ \| EV::PERSIST, sub {	27	my $w = EV::io *STDIN, EV::READ, sub {
28	my ($w, $events) = @_; # all callbacks get the watcher object and event mask	28	my ($w, $revents) = @_; # 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>;	29	warn "stdin is readable, you entered: ", <STDIN>;
33	}
34	};	30	};
35	$w->timeout (10);	31
		32	# SIGNALS
		33
		34	my $w = EV::signal 'QUIT', sub {
		35	warn "sigquit received\n";
		36	};
		37
		38	my $w = EV::signal 3, sub {
		39	warn "sigquit received (this is GNU/Linux, right?)\n";
		40	};
36		41
		42	# CHILD/PID STATUS CHANGES
		43
		44	my $w = EV::child 666, sub {
		45	my ($w, $revents, $status) = @_;
		46	};
		47
37	# MAINLOOP	48	# MAINLOOP
38	EV::dispatch; # loop as long as watchers are active	49	EV::loop; # loop until EV::loop_done is called
39	EV::loop; # the same thing	50	EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled
40	EV::loop EV::LOOP_ONCE;	51	EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
41	EV::loop EV::LOOP_ONSHOT;
42		52
43	=head1 DESCRIPTION	53	=head1 DESCRIPTION
44		54
45	This module provides an interface to libevent	55	This module provides an interface to libev
46	(L<http://monkey.org/~provos/libevent/>). You probably should acquaint	56	(L<http://software.schmorp.de/pkg/libev.html>).
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		57
53	=cut	58	=cut
54		59
55	package EV;	60	package EV;
56		61
57	use strict;	62	use strict;
58		63
59	BEGIN {	64	BEGIN {
60	our $VERSION = '0.01';	65	our $VERSION = '0.1';
61	use XSLoader;	66	use XSLoader;
62	XSLoader::load "EV", $VERSION;	67	XSLoader::load "EV", $VERSION;
63	}	68	}
64		69
65	=head1 FUNCTIONAL INTERFACE	70	@EV::Io::ISA =
		71	@EV::Timer::ISA =
		72	@EV::Periodic::ISA =
		73	@EV::Signal::ISA =
		74	@EV::Idle::ISA =
		75	@EV::Prepare::ISA =
		76	@EV::Check::ISA =
		77	@EV::Child::ISA = "EV::Watcher";
		78
		79	=head1 BASIC INTERFACE
66		80
67	=over 4	81	=over 4
68		82
69	=item $EV::NPRI	83	=item $EV::DIED
70		84
71	How many priority levels are available.	85	Must contain a reference to a function that is called when a callback
		86	throws an exception (with $@ containing thr error). The default prints an
		87	informative message and continues.
		88
		89	If this callback throws an exception it will be silently ignored.
		90
		91	=item $time = EV::time
		92
		93	Returns the current time in (fractional) seconds since the epoch.
72		94
73	=item $time = EV::now	95	=item $time = EV::now
74		96
75	Returns the time in (fractional) seconds since the epoch.	97	Returns the time the last event loop iteration has been started. This
		98	is the time that (relative) timers are based on, and refering to it is
		99	usually faster then calling EV::time.
76		100
77	=item $version = EV::version
78
79	=item $method = EV::method	101	=item $method = EV::ev_method
80		102
81	Return version string and event polling method used.	103	Returns an integer describing the backend used by libev (EV::METHOD_SELECT
		104	or EV::METHOD_EPOLL).
82		105
83	=item EV::loop $flags # EV::LOOP_ONCE, EV::LOOP_ONESHOT	106	=item EV::loop [$flags]
84		107
85	=item EV::loopexit $after	108	Begin checking for events and calling callbacks. It returns when a
		109	callback calls EV::loop_done.
86		110
87	Exit any active loop or dispatch after C<$after> seconds or immediately if	111	The $flags argument can be one of the following:
88	C<$after> is missing or zero.
89		112
90	=item EV::dispatch	113	0 as above
		114	EV::LOOP_ONESHOT block at most once (wait, but do not loop)
		115	EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait)
91		116
92	Same as C<EV::loop 0>.	117	=item EV::loop_done [$how]
93		118
94	=item EV::event $callback	119	When called with no arguments or an argument of 1, makes the innermost
		120	call to EV::loop return.
95		121
96	Creates a new event watcher waiting for nothing, calling the given callback.	122	When called with an agrument of 2, all calls to EV::loop will return as
		123	fast as possible.
97		124
		125	=back
		126
		127	=head2 WATCHER
		128
		129	A watcher is an object that gets created to record your interest in some
		130	event. For instance, if you want to wait for STDIN to become readable, you
		131	would create an EV::io watcher for that:
		132
		133	my $watcher = EV::io *STDIN, EV::READ, sub {
		134	my ($watcher, $revents) = @_;
		135	warn "yeah, STDIN should not be readable without blocking!\n"
		136	};
		137
		138	All watchers can be active (waiting for events) or inactive (paused). Only
		139	active watchers will have their callbacks invoked. All callbacks will be
		140	called with at least two arguments: the watcher and a bitmask of received
		141	events.
		142
		143	Each watcher type has its associated bit in revents, so you can use the
		144	same callback for multiple watchers. The event mask is named after the
		145	type, i..e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
		146	EV::periodic sets EV::PERIODIC and so on, with the exception of IO events
		147	(which can set both EV::READ and EV::WRITE bits), and EV::timer (which
		148	uses EV::TIMEOUT).
		149
		150	In the rare case where one wants to create a watcher but not start it at
		151	the same time, each constructor has a variant with a trailing C<_ns> in
		152	its name, e.g. EV::io has a non-starting variant EV::io_ns and so on.
		153
		154	Please note that a watcher will automatically be stopped when the watcher
		155	object is returned, so you I<need> to keep the watcher objects returned by
		156	the constructors.
		157
		158	=head2 WATCHER TYPES
		159
		160	Now lets move to the existing watcher types and asociated methods.
		161
		162	The following methods are available for all watchers. Then followes a
		163	description of each watcher constructor (EV::io, EV::timer, EV::periodic,
		164	EV::signal, EV::child, EV::idle, EV::prepare and EV::check), followed by
		165	any type-specific methods (if any).
		166
		167	=over 4
		168
		169	=item $w->start
		170
		171	Starts a watcher if it isn't active already. Does nothing to an already
		172	active watcher. By default, all watchers start out in the active state
		173	(see the description of the C<_ns> variants if you need stopped watchers).
		174
		175	=item $w->stop
		176
		177	Stop a watcher if it is active. Also clear any pending events (events that
		178	have been received but that didn't yet result in a callback invocation),
		179	regardless of wether the watcher was active or not.
		180
		181	=item $bool = $w->is_active
		182
		183	Returns true if the watcher is active, false otherwise.
		184
		185	=item $current_cb = $w->cb
		186
		187	=item $old_cb = $w->cb ($new_cb)
		188
		189	Queries the callback on the watcher and optionally changes it. You cna do
		190	this at any time.
		191
		192	=item $w->trigger ($revents)
		193
		194	Call the callback now with the given event mask.
		195
		196
98	=item my $w = EV::io $fileno_or_fh, $eventmask, $callback	197	=item $w = EV::io $fileno_or_fh, $eventmask, $callback
99		198
100	=item my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback	199	=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
101		200
102	As long as the returned watcher object is alive, call the C<$callback>	201	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	202	when the events specified in C<$eventmask>.
104	is disabled.
105		203
106	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
114	Eventmask can be one or more of these constants ORed together:	204	The $eventmask can be one or more of these constants ORed together:
115		205
116	EV::READ wait until read() wouldn't block anymore	206	EV::READ wait until read() wouldn't block anymore
117	EV::WRITE wait until write() wouldn't block anymore	207	EV::WRITE wait until write() wouldn't block anymore
118	EV::PERSIST stay active after a (non-timeout) event occured
119		208
120	The C<io_ns> variant doesn't add/start the newly created watcher.	209	The C<io_ns> variant doesn't start (activate) the newly created watcher.
121		210
		211	=item $w->set ($fileno_or_fh, $eventmask)
		212
		213	Reconfigures the watcher, see the constructor above for details. Can be
		214	called at any time.
		215
		216	=item $current_fh = $w->fh
		217
		218	=item $old_fh = $w->fh ($new_fh)
		219
		220	Returns the previously set filehandle and optionally set a new one.
		221
		222	=item $current_eventmask = $w->events
		223
		224	=item $old_eventmask = $w->events ($new_eventmask)
		225
		226	Returns the previously set event mask and optionally set a new one.
		227
		228
122	=item my $w = EV::timer $after, $repeat, $callback	229	=item $w = EV::timer $after, $repeat, $callback
123		230
124	=item my $w = EV::timer_ns $after, $repeat, $callback	231	=item $w = EV::timer_ns $after, $repeat, $callback
125		232
126	Calls the callback after C<$after> seconds. If C<$repeat> is true, the	233	Calls the callback after C<$after> seconds. If C<$repeat> is non-zero,
127	timer will be restarted after the callback returns. This means that the	234	the timer will be restarted (with the $repeat value as $after) after the
128	callback would be called roughly every C<$after> seconds, prolonged by the	235	callback returns.
129	time the callback takes.
130		236
		237	This means that the callback would be called roughly after C<$after>
		238	seconds, and then every C<$repeat> seconds. "Roughly" because the time of
		239	callback processing is not taken into account, so the timer will slowly
		240	drift. If that isn't acceptable, look at EV::periodic.
		241
		242	The timer is based on a monotonic clock, that is if somebody is sitting
		243	in front of the machine while the timer is running and changes the system
		244	clock, the timer will nevertheless run (roughly) the same time.
		245
131	The C<timer_ns> variant doesn't add/start the newly created watcher.	246	The C<timer_ns> variant doesn't start (activate) the newly created watcher.
132		247
		248	=item $w->set ($after, $repeat)
		249
		250	Reconfigures the watcher, see the constructor above for details. Can be at
		251	any time.
		252
		253	=item $w->again
		254
		255	Similar to the C<start> method, but has special semantics for repeating timers:
		256
		257	If the timer is active and repeating, reset the timeout to occur
		258	C<$repeat> seconds after now.
		259
		260	If the timer is active and non-repeating, it will be stopped.
		261
		262	If the timer is in active and repeating, start it.
		263
		264	Otherwise do nothing.
		265
		266	This behaviour is useful when you have a timeout for some IO
		267	operation. You create a timer object with the same value for C<$after> and
		268	C<$repeat>, and then, in the read/write watcher, run the C<again> method
		269	on the timeout.
		270
		271
		272	=item $w = EV::periodic $at, $interval, $callback
		273
133	=item my $w = EV::timer_abs $at, $interval, $callback	274	=item $w = EV::periodic_ns $at, $interval, $callback
134
135	=item my $w = EV::timer_abs_ns $at, $interval, $callback
136		275
137	Similar to EV::timer, but the time is given as an absolute point in time	276	Similar to EV::timer, but the time is given as an absolute point in time
138	(C<$at>), plus an optional C<$interval>.	277	(C<$at>), plus an optional C<$interval>.
139		278
140	If the C<$interval> is zero, then the callback will be called at the time	279	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	280	C<$at> if that is in the future, or as soon as possible if it is in the
142	past. It will not automatically repeat.	281	past. It will not automatically repeat.
143		282
144	If the C<$interval> is nonzero, then the watcher will always be scheduled	283	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.	284	to time out at the next C<$at + N * $interval> time.
146		285
147	This can be used to schedule a callback to run at very regular intervals,	286	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	287	as long as the processing time is less then the interval (otherwise
149	obviously events will be skipped).	288	obviously events will be skipped).
150		289
151	Another way to think about it (for the mathematically inclined) is that	290	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	291	EV::periodic will try to run the callback at the next possible time where
153	C<$time = $at (mod $interval)>, regardless of any time jumps.	292	C<$time = $at (mod $interval)>, regardless of any time jumps.
154		293
		294	This periodic timer is based on "wallclock time", that is, if the clock
		295	changes (C<ntp>, C<date -s> etc.), then the timer will nevertheless run at
		296	the specified time. This means it will never drift (it might jitter, but
		297	it will not drift).
		298
155	The C<timer_abs_ns> variant doesn't add/start the newly created watcher.	299	The C<periodic_ns> variant doesn't start (activate) the newly created watcher.
156		300
		301	=item $w->set ($at, $interval)
		302
		303	Reconfigures the watcher, see the constructor above for details. Can be at
		304	any time.
		305
		306
157	=item my $w = EV::signal $signum, $callback	307	=item $w = EV::signal $signal, $callback
158		308
159	=item my $w = EV::signal_ns $signum, $callback	309	=item $w = EV::signal_ns $signal, $callback
160		310
161	Call the callback when signal $signum is received.	311	Call the callback when $signal is received (the signal can be specified
		312	by number or by name, just as with kill or %SIG).
162		313
		314	EV will grab the signal for the process (the kernel only allows one
		315	component to receive a signal at a time) when you start a signal watcher,
		316	and removes it again when you stop it. Perl does the same when you
		317	add/remove callbacks to %SIG, so watch out.
		318
		319	You can have as many signal watchers per signal as you want.
		320
163	The C<signal_ns> variant doesn't add/start the newly created watcher.	321	The C<signal_ns> variant doesn't start (activate) the newly created watcher.
		322
		323	=item $w->set ($signal)
		324
		325	Reconfigures the watcher, see the constructor above for details. Can be at
		326	any time.
		327
		328	=item $current_signum = $w->signal
		329
		330	=item $old_signum = $w->signal ($new_signal)
		331
		332	Returns the previously set signal (always as a number not name) and
		333	optionally set a new one.
		334
		335
		336	=item $w = EV::child $pid, $callback
		337
		338	=item $w = EV::child_ns $pid, $callback
		339
		340	Call the callback when a status change for pid C<$pid> (or any pid
		341	if C<$pid> is 0) has been received. More precisely: when the process
		342	receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all
		343	changed/zombie children and call the callback.
		344
		345	Unlike all other callbacks, this callback will be called with an
		346	additional third argument which is the exit status. See the C<waitpid>
		347	function for details.
		348
		349	You can have as many pid watchers per pid as you want.
		350
		351	The C<child_ns> variant doesn't start (activate) the newly created watcher.
		352
		353	=item $w->set ($pid)
		354
		355	Reconfigures the watcher, see the constructor above for details. Can be at
		356	any time.
		357
		358	=item $current_pid = $w->pid
		359
		360	=item $old_pid = $w->pid ($new_pid)
		361
		362	Returns the previously set process id and optionally set a new one.
		363
		364
		365	=item $w = EV::idle $callback
		366
		367	=item $w = EV::idle_ns $callback
		368
		369	Call the callback when there are no pending io, timer/periodic, signal or
		370	child events, i.e. when the process is idle.
		371
		372	The process will not block as long as any idle watchers are active, and
		373	they will be called repeatedly until stopped.
		374
		375	The C<idle_ns> variant doesn't start (activate) the newly created watcher.
		376
		377
		378	=item $w = EV::prepare $callback
		379
		380	=item $w = EV::prepare_ns $callback
		381
		382	Call the callback just before the process would block. You can still
		383	create/modify any watchers at this point.
		384
		385	See the EV::check watcher, below, for explanations and an example.
		386
		387	The C<prepare_ns> variant doesn't start (activate) the newly created watcher.
		388
		389
		390	=item $w = EV::check $callback
		391
		392	=item $w = EV::check_ns $callback
		393
		394	Call the callback just after the process wakes up again (after it has
		395	gathered events), but before any other callbacks have been invoked.
		396
		397	This is used to integrate other event-based software into the EV
		398	mainloop: You register a prepare callback and in there, you create io and
		399	timer watchers as required by the other software. Here is a real-world
		400	example of integrating Net::SNMP (with some details left out):
		401
		402	our @snmp_watcher;
		403
		404	our $snmp_prepare = EV::prepare sub {
		405	# do nothing unless active
		406	$dispatcher->{_event_queue_h}
		407	or return;
		408
		409	# make the dispatcher handle any outstanding stuff
		410
		411	# create an IO watcher for each and every socket
		412	@snmp_watcher = (
		413	(map { EV::io $_, EV::READ, sub { } }
		414	keys %{ $dispatcher->{_descriptors} }),
		415	);
		416
		417	# if there are any timeouts, also create a timer
		418	push @snmp_watcher, EV::timer $event->[Net::SNMP::Dispatcher::_TIME] - EV::now, 0, sub { }
		419	if $event->[Net::SNMP::Dispatcher::_ACTIVE];
		420	};
		421
		422	The callbacks are irrelevant, the only purpose of those watchers is
		423	to wake up the process as soon as one of those events occurs (socket
		424	readable, or timer timed out). The corresponding EV::check watcher will then
		425	clean up:
		426
		427	our $snmp_check = EV::check sub {
		428	# destroy all watchers
		429	@snmp_watcher = ();
		430
		431	# make the dispatcher handle any new stuff
		432	};
		433
		434	The callbacks of the created watchers will not be called as the watchers
		435	are destroyed before this cna happen (remember EV::check gets called
		436	first).
		437
		438	The C<check_ns> variant doesn't start (activate) the newly created watcher.
164		439
165	=back	440	=back
166		441
167	=head1 THE EV::Event CLASS	442	=head1 THREADS
168		443
169	All EV functions creating an event watcher (designated by C<my $w =>	444	Threads are not supported by this in any way. Perl pseudo-threads is evil
170	above) support the following methods on the returned watcher object:	445	stuff and must die.
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
187	Stop the event watcher if it was started.
188
189	=item $current_callback = $w->cb
190
191	=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
219	=back
220
221	=head1 BUGS
222
223	Lots. Libevent itself isn't well tested and rather buggy, and this module
224	is quite new at the moment.
225
226	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		446
234	=cut	447	=cut
235		448
236	our $NPRI = 4;	449	our $DIED = sub {
237	our $BASE = init;	450	warn "EV: error in callback (ignoring): $@";
238	priority_init $NPRI;	451	};
		452
		453	init;
239		454
240	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];	455	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
241		456
242	1;	457	1;
243		458
244	=head1 SEE ALSO	459	=head1 SEE ALSO
245		460
246	L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
247	L<EV::AnyEvent>.	461	L<EV::DNS>, L<EV::AnyEvent>.
248		462
249	=head1 AUTHOR	463	=head1 AUTHOR
250		464
251	Marc Lehmann <schmorp@schmorp.de>	465	Marc Lehmann <schmorp@schmorp.de>
252	http://home.schmorp.de/	466	http://home.schmorp.de/

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing EV/EV.pm (file contents): Revision 1.7 by root, Sat Oct 27 14:54:20 2007 UTC vs. Revision 1.22 by root, Fri Nov 2 11:02:22 2007 UTC

Diff Legend

Comparing EV/EV.pm (file contents):
Revision 1.7 by root, Sat Oct 27 14:54:20 2007 UTC vs.
Revision 1.22 by root, Fri Nov 2 11:02:22 2007 UTC