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

Comparing EV/EV.pm (file contents):
Revision 1.4 by root, Fri Oct 26 19:11:35 2007 UTC vs.
Revision 1.24 by root, Fri Nov 2 22:03:00 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/>).	56	(L<http://software.schmorp.de/pkg/libev.html>).
47		57
48	=cut	58	=cut
49		59
50	package EV;	60	package EV;
51		61
52	use strict;	62	use strict;
53		63
54	BEGIN {	64	BEGIN {
55	our $VERSION = '0.01';	65	our $VERSION = '0.1';
56	use XSLoader;	66	use XSLoader;
57	XSLoader::load "EV", $VERSION;	67	XSLoader::load "EV", $VERSION;
58	}	68	}
59		69
60	=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
61		80
62	=over 4	81	=over 4
63		82
64	=item $EV::NPRI	83	=item $EV::DIED
65		84
66	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.
67		94
68	=item $time = EV::now	95	=item $time = EV::now
69		96
70	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.
71		100
72	=item $version = EV::version
73
74	=item $method = EV::method	101	=item $method = EV::ev_method
75		102
76	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).
77		105
78	=item EV::loop $flags # EV::LOOP_ONCE, EV::LOOP_ONESHOT	106	=item EV::loop [$flags]
79		107
80	=item EV::loopexit $after	108	Begin checking for events and calling callbacks. It returns when a
		109	callback calls EV::loop_done.
81		110
82	Exit any active loop or dispatch after C<$after> seconds or immediately if	111	The $flags argument can be one of the following:
83	C<$after> is missing or zero.
84		112
85	=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)
86		116
87	Same as C<EV::loop 0>.	117	=item EV::loop_done [$how]
88		118
89	=item EV::event $callback	119	When called with no arguments or an argument of 1, makes the innermost
		120	call to EV::loop return.
90		121
91	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.
92		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 destroyed, so you I<need> to keep the watcher objects returned by
		156	the constructors.
		157
		158	Also, all methods changing some aspect of a watcher (->set, ->priority,
		159	->fh and so on) automatically stop and start it again if it is active,
		160	which means pending events get lost.
		161
		162	=head2 WATCHER TYPES
		163
		164	Now lets move to the existing watcher types and asociated methods.
		165
		166	The following methods are available for all watchers. Then followes a
		167	description of each watcher constructor (EV::io, EV::timer, EV::periodic,
		168	EV::signal, EV::child, EV::idle, EV::prepare and EV::check), followed by
		169	any type-specific methods (if any).
		170
		171	=over 4
		172
		173	=item $w->start
		174
		175	Starts a watcher if it isn't active already. Does nothing to an already
		176	active watcher. By default, all watchers start out in the active state
		177	(see the description of the C<_ns> variants if you need stopped watchers).
		178
		179	=item $w->stop
		180
		181	Stop a watcher if it is active. Also clear any pending events (events that
		182	have been received but that didn't yet result in a callback invocation),
		183	regardless of wether the watcher was active or not.
		184
		185	=item $bool = $w->is_active
		186
		187	Returns true if the watcher is active, false otherwise.
		188
		189	=item $current_cb = $w->cb
		190
		191	=item $old_cb = $w->cb ($new_cb)
		192
		193	Queries the callback on the watcher and optionally changes it. You can do
		194	this at any time without the watcher restarting.
		195
		196	=item $current_priority = $w->priority
		197
		198	=item $old_priority = $w->priority ($new_priority)
		199
		200	Queries the priority on the watcher and optionally changes it. Pending
		201	watchers with higher priority will be invoked first. The valid range of
		202	priorities lies between EV::MAXPRI (default 2) and EV::MINPRI (default
		203	-2). If the priority is outside this range it will automatically be
		204	normalised to the nearest valid priority.
		205
		206	The default priority of any newly-created weatcher is 0.
		207
		208	=item $w->trigger ($revents)
		209
		210	Call the callback now with the given event mask.
		211
		212
93	=item my $w = EV::io $fileno_or_fh, $eventmask, $callback	213	=item $w = EV::io $fileno_or_fh, $eventmask, $callback
94		214
95	=item my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback	215	=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
96		216
97	As long as the returned watcher object is alive, call the C<$callback>	217	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	218	when the events specified in C<$eventmask>.
99	is disabled.
100		219
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:	220	The $eventmask can be one or more of these constants ORed together:
104		221
105	EV::READ wait until read() wouldn't block anymore	222	EV::READ wait until read() wouldn't block anymore
106	EV::WRITE wait until write() wouldn't block anymore	223	EV::WRITE wait until write() wouldn't block anymore
107	EV::PERSIST stay active after an event occured
108		224
		225	The C<io_ns> variant doesn't start (activate) the newly created watcher.
		226
		227	=item $w->set ($fileno_or_fh, $eventmask)
		228
		229	Reconfigures the watcher, see the constructor above for details. Can be
		230	called at any time.
		231
		232	=item $current_fh = $w->fh
		233
		234	=item $old_fh = $w->fh ($new_fh)
		235
		236	Returns the previously set filehandle and optionally set a new one.
		237
		238	=item $current_eventmask = $w->events
		239
		240	=item $old_eventmask = $w->events ($new_eventmask)
		241
		242	Returns the previously set event mask and optionally set a new one.
		243
		244
109	=item my $w = EV::timer $after, $repeat, $callback	245	=item $w = EV::timer $after, $repeat, $callback
110		246
111	=item my $w = EV::timer_ns $after, $repeat, $callback	247	=item $w = EV::timer_ns $after, $repeat, $callback
112		248
113	Calls the callback after C<$after> seconds. If C<$repeat> is true, the	249	Calls the callback after C<$after> seconds. If C<$repeat> is non-zero,
114	timer will be restarted after the callback returns. This means that the	250	the timer will be restarted (with the $repeat value as $after) after the
115	callback would be called roughly every C<$after> seconds, prolonged by the	251	callback returns.
116	time the callback takes.
117		252
		253	This means that the callback would be called roughly after C<$after>
		254	seconds, and then every C<$repeat> seconds. "Roughly" because the time of
		255	callback processing is not taken into account, so the timer will slowly
		256	drift. If that isn't acceptable, look at EV::periodic.
		257
		258	The timer is based on a monotonic clock, that is if somebody is sitting
		259	in front of the machine while the timer is running and changes the system
		260	clock, the timer will nevertheless run (roughly) the same time.
		261
118	The C<timer_ns> variant doesn't add/start the newly created watcher.	262	The C<timer_ns> variant doesn't start (activate) the newly created watcher.
119		263
		264	=item $w->set ($after, $repeat)
		265
		266	Reconfigures the watcher, see the constructor above for details. Can be at
		267	any time.
		268
		269	=item $w->again
		270
		271	Similar to the C<start> method, but has special semantics for repeating timers:
		272
		273	If the timer is active and repeating, reset the timeout to occur
		274	C<$repeat> seconds after now.
		275
		276	If the timer is active and non-repeating, it will be stopped.
		277
		278	If the timer is in active and repeating, start it.
		279
		280	Otherwise do nothing.
		281
		282	This behaviour is useful when you have a timeout for some IO
		283	operation. You create a timer object with the same value for C<$after> and
		284	C<$repeat>, and then, in the read/write watcher, run the C<again> method
		285	on the timeout.
		286
		287
		288	=item $w = EV::periodic $at, $interval, $callback
		289
120	=item my $w = EV::timer_abs $at, $interval, $callback	290	=item $w = EV::periodic_ns $at, $interval, $callback
121
122	=item my $w = EV::timer_abs_ns $at, $interval, $callback
123		291
124	Similar to EV::timer, but the time is given as an absolute point in time	292	Similar to EV::timer, but the time is given as an absolute point in time
125	(C<$at>), plus an optional C<$interval>.	293	(C<$at>), plus an optional C<$interval>.
126		294
127	If the C<$interval> is zero, then the callback will be called at the time	295	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	296	C<$at> if that is in the future, or as soon as possible if it is in the
129	past. It will not automatically repeat.	297	past. It will not automatically repeat.
130		298
131	If the C<$interval> is nonzero, then the watcher will always be scheduled	299	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.	300	to time out at the next C<$at + N * $interval> time.
133		301
134	This can be used to schedule a callback to run at very regular intervals,	302	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	303	as long as the processing time is less then the interval (otherwise
136	obviously events will be skipped).	304	obviously events will be skipped).
137		305
		306	Another way to think about it (for the mathematically inclined) is that
		307	EV::periodic will try to run the callback at the next possible time where
		308	C<$time = $at (mod $interval)>, regardless of any time jumps.
		309
		310	This periodic timer is based on "wallclock time", that is, if the clock
		311	changes (C<ntp>, C<date -s> etc.), then the timer will nevertheless run at
		312	the specified time. This means it will never drift (it might jitter, but
		313	it will not drift).
		314
138	The C<timer_abs_ns> variant doesn't add/start the newly created watcher.	315	The C<periodic_ns> variant doesn't start (activate) the newly created watcher.
139		316
		317	=item $w->set ($at, $interval)
		318
		319	Reconfigures the watcher, see the constructor above for details. Can be at
		320	any time.
		321
		322
140	=item my $w = EV::signal $signum, $callback	323	=item $w = EV::signal $signal, $callback
141		324
142	=item my $w = EV::signal_ns $signum, $callback	325	=item $w = EV::signal_ns $signal, $callback
143		326
144	Call the callback when signal $signum is received.	327	Call the callback when $signal is received (the signal can be specified
		328	by number or by name, just as with kill or %SIG).
145		329
		330	EV will grab the signal for the process (the kernel only allows one
		331	component to receive a signal at a time) when you start a signal watcher,
		332	and removes it again when you stop it. Perl does the same when you
		333	add/remove callbacks to %SIG, so watch out.
		334
		335	You can have as many signal watchers per signal as you want.
		336
146	The C<signal_ns> variant doesn't add/start the newly created watcher.	337	The C<signal_ns> variant doesn't start (activate) the newly created watcher.
		338
		339	=item $w->set ($signal)
		340
		341	Reconfigures the watcher, see the constructor above for details. Can be at
		342	any time.
		343
		344	=item $current_signum = $w->signal
		345
		346	=item $old_signum = $w->signal ($new_signal)
		347
		348	Returns the previously set signal (always as a number not name) and
		349	optionally set a new one.
		350
		351
		352	=item $w = EV::child $pid, $callback
		353
		354	=item $w = EV::child_ns $pid, $callback
		355
		356	Call the callback when a status change for pid C<$pid> (or any pid
		357	if C<$pid> is 0) has been received. More precisely: when the process
		358	receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all
		359	changed/zombie children and call the callback.
		360
		361	Unlike all other callbacks, this callback will be called with an
		362	additional third argument which is the exit status. See the C<waitpid>
		363	function for details.
		364
		365	You can have as many pid watchers per pid as you want.
		366
		367	The C<child_ns> variant doesn't start (activate) the newly created watcher.
		368
		369	=item $w->set ($pid)
		370
		371	Reconfigures the watcher, see the constructor above for details. Can be at
		372	any time.
		373
		374	=item $current_pid = $w->pid
		375
		376	=item $old_pid = $w->pid ($new_pid)
		377
		378	Returns the previously set process id and optionally set a new one.
		379
		380
		381	=item $w = EV::idle $callback
		382
		383	=item $w = EV::idle_ns $callback
		384
		385	Call the callback when there are no pending io, timer/periodic, signal or
		386	child events, i.e. when the process is idle.
		387
		388	The process will not block as long as any idle watchers are active, and
		389	they will be called repeatedly until stopped.
		390
		391	The C<idle_ns> variant doesn't start (activate) the newly created watcher.
		392
		393
		394	=item $w = EV::prepare $callback
		395
		396	=item $w = EV::prepare_ns $callback
		397
		398	Call the callback just before the process would block. You can still
		399	create/modify any watchers at this point.
		400
		401	See the EV::check watcher, below, for explanations and an example.
		402
		403	The C<prepare_ns> variant doesn't start (activate) the newly created watcher.
		404
		405
		406	=item $w = EV::check $callback
		407
		408	=item $w = EV::check_ns $callback
		409
		410	Call the callback just after the process wakes up again (after it has
		411	gathered events), but before any other callbacks have been invoked.
		412
		413	This is used to integrate other event-based software into the EV
		414	mainloop: You register a prepare callback and in there, you create io and
		415	timer watchers as required by the other software. Here is a real-world
		416	example of integrating Net::SNMP (with some details left out):
		417
		418	our @snmp_watcher;
		419
		420	our $snmp_prepare = EV::prepare sub {
		421	# do nothing unless active
		422	$dispatcher->{_event_queue_h}
		423	or return;
		424
		425	# make the dispatcher handle any outstanding stuff
		426
		427	# create an IO watcher for each and every socket
		428	@snmp_watcher = (
		429	(map { EV::io $_, EV::READ, sub { } }
		430	keys %{ $dispatcher->{_descriptors} }),
		431	);
		432
		433	# if there are any timeouts, also create a timer
		434	push @snmp_watcher, EV::timer $event->[Net::SNMP::Dispatcher::_TIME] - EV::now, 0, sub { }
		435	if $event->[Net::SNMP::Dispatcher::_ACTIVE];
		436	};
		437
		438	The callbacks are irrelevant, the only purpose of those watchers is
		439	to wake up the process as soon as one of those events occurs (socket
		440	readable, or timer timed out). The corresponding EV::check watcher will then
		441	clean up:
		442
		443	our $snmp_check = EV::check sub {
		444	# destroy all watchers
		445	@snmp_watcher = ();
		446
		447	# make the dispatcher handle any new stuff
		448	};
		449
		450	The callbacks of the created watchers will not be called as the watchers
		451	are destroyed before this cna happen (remember EV::check gets called
		452	first).
		453
		454	The C<check_ns> variant doesn't start (activate) the newly created watcher.
147		455
148	=back	456	=back
149		457
150	=head1 THE EV::Event CLASS	458	=head1 THREADS
151		459
152	All EV functions creating an event watcher (designated by C<my $w =>	460	Threads are not supported by this in any way. Perl pseudo-threads is evil
153	above) support the following methods on the returned watcher object:	461	stuff and must die.
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		462
209	=cut	463	=cut
210		464
211	our $NPRI = 4;	465	our $DIED = sub {
212	our $BASE = init;	466	warn "EV: error in callback (ignoring): $@";
213	priority_init $NPRI;	467	};
		468
		469	init;
214		470
215	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];	471	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
216		472
217	1;	473	1;
218		474
219	=head1 SEE ALSO	475	=head1 SEE ALSO
220		476
221	L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.	477	L<EV::DNS>, L<EV::AnyEvent>.
222		478
223	=head1 AUTHOR	479	=head1 AUTHOR
224		480
225	Marc Lehmann <schmorp@schmorp.de>	481	Marc Lehmann <schmorp@schmorp.de>
226	http://home.schmorp.de/	482	http://home.schmorp.de/

Diff Legend

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

Comparing EV/EV.pm (file contents): Revision 1.4 by root, Fri Oct 26 19:11:35 2007 UTC vs. Revision 1.24 by root, Fri Nov 2 22:03:00 2007 UTC

Diff Legend

Comparing EV/EV.pm (file contents):
Revision 1.4 by root, Fri Oct 26 19:11:35 2007 UTC vs.
Revision 1.24 by root, Fri Nov 2 22:03:00 2007 UTC