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

Comparing EV/EV.pm (file contents):
Revision 1.1 by root, Fri Oct 26 16:50:05 2007 UTC vs.
Revision 1.20 by root, Thu Nov 1 17:17:32 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
		9	# TIMERS
		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	my $w = EV::periodic 0, 60, sub {
		22	warn "is called every minute, on the minute, exactly";
		23	};
		24
		25	# IO
		26
		27	my $w = EV::io *STDIN, EV::READ, sub {
		28	my ($w, $revents) = @_; # all callbacks get the watcher object and event mask
		29	warn "stdin is readable, you entered: ", <STDIN>;
		30	};
		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	};
		41
		42	# CHILD/PID STATUS CHANGES
		43
		44	my $w = EV::child 666, sub {
		45	my ($w, $revents, $status) = @_;
		46	};
		47
		48	# MAINLOOP
		49	EV::loop; # loop until EV::loop_done is called
		50	EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled
		51	EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
8		52
9	=head1 DESCRIPTION	53	=head1 DESCRIPTION
10		54
11	This module provides an interface to libevent	55	This module provides an interface to libev
12	(L<http://monkey.org/~provos/libevent/>).	56	(L<http://software.schmorp.de/pkg/libev.html>).
13		57
14	=cut	58	=cut
15		59
16	package EV;	60	package EV;
17		61
18	use strict;	62	use strict;
19		63
20	BEGIN {	64	BEGIN {
21	our $VERSION = '0.01';	65	our $VERSION = '0.1';
22	use XSLoader;	66	use XSLoader;
23	XSLoader::load "EV", $VERSION;	67	XSLoader::load "EV", $VERSION;
24	}	68	}
25		69
26	=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
27		80
28	=over 4	81	=over 4
29		82
		83	=item $EV::DIED
		84
		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.
		94
		95	=item $time = EV::now
		96
		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.
		100
		101	=item $method = EV::ev_method
		102
		103	Returns an integer describing the backend used by libev (EV::METHOD_SELECT
		104	or EV::METHOD_EPOLL).
		105
		106	=item EV::loop [$flags]
		107
		108	Begin checking for events and calling callbacks. It returns when a
		109	callback calls EV::loop_done.
		110
		111	The $flags argument can be one of the following:
		112
		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)
		116
		117	=item EV::loop_done [$how]
		118
		119	When called with no arguments or an argument of 1, makes the innermost
		120	call to EV::loop return.
		121
		122	When called with an agrument of 2, all calls to EV::loop will return as
		123	fast as possible.
		124
30	=back	125	=back
31		126
		127	=head2 WATCHER
32		128
33	=head1 OBJECT-ORIENTED INTERFACE	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:
34		132
35	The object oriented interface lets you configure your own encoding or	133	my $watcher = EV::io *STDIN, EV::READ, sub {
36	decoding style, within the limits of supported formats.	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).
37		166
38	=over 4	167	=over 4
39		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
		197	=item $w = EV::io $fileno_or_fh, $eventmask, $callback
		198
		199	=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
		200
		201	As long as the returned watcher object is alive, call the C<$callback>
		202	when the events specified in C<$eventmask>.
		203
		204	The $eventmask can be one or more of these constants ORed together:
		205
		206	EV::READ wait until read() wouldn't block anymore
		207	EV::WRITE wait until write() wouldn't block anymore
		208
		209	The C<io_ns> variant doesn't start (activate) the newly created watcher.
		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
		229	=item $w = EV::timer $after, $repeat, $callback
		230
		231	=item $w = EV::timer_ns $after, $repeat, $callback
		232
		233	Calls the callback after C<$after> seconds. If C<$repeat> is non-zero,
		234	the timer will be restarted (with the $repeat value as $after) after the
		235	callback returns.
		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
		246	The C<timer_ns> variant doesn't start (activate) the newly created watcher.
		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
		274	=item $w = EV::periodic_ns $at, $interval, $callback
		275
		276	Similar to EV::timer, but the time is given as an absolute point in time
		277	(C<$at>), plus an optional C<$interval>.
		278
		279	If the C<$interval> is zero, then the callback will be called at the time
		280	C<$at> if that is in the future, or as soon as possible if it is in the
		281	past. It will not automatically repeat.
		282
		283	If the C<$interval> is nonzero, then the watcher will always be scheduled
		284	to time out at the next C<$at + N * $interval> time.
		285
		286	This can be used to schedule a callback to run at very regular intervals,
		287	as long as the processing time is less then the interval (otherwise
		288	obviously events will be skipped).
		289
		290	Another way to think about it (for the mathematically inclined) is that
		291	EV::periodic will try to run the callback at the next possible time where
		292	C<$time = $at (mod $interval)>, regardless of any time jumps.
		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.
		297
		298	The C<periodic_ns> variant doesn't start (activate) the newly created watcher.
		299
		300	=item $w->set ($at, $interval)
		301
		302	Reconfigures the watcher, see the constructor above for details. Can be at
		303	any time.
		304
		305
		306	=item $w = EV::signal $signal, $callback
		307
		308	=item $w = EV::signal_ns $signal, $callback
		309
		310	Call the callback when $signal is received (the signal can be specified
		311	by number or by name, just as with kill or %SIG).
		312
		313	EV will grab the signal for the process (the kernel only allows one
		314	component to receive a signal at a time) when you start a signal watcher,
		315	and removes it again when you stop it. Perl does the same when you
		316	add/remove callbacks to %SIG, so watch out.
		317
		318	You can have as many signal watchers per signal as you want.
		319
		320	The C<signal_ns> variant doesn't start (activate) the newly created watcher.
		321
		322	=item $w->set ($signal)
		323
		324	Reconfigures the watcher, see the constructor above for details. Can be at
		325	any time.
		326
		327
		328	=item $w = EV::child $pid, $callback
		329
		330	=item $w = EV::child_ns $pid, $callback
		331
		332	Call the callback when a status change for pid C<$pid> (or any pid
		333	if C<$pid> is 0) has been received. More precisely: when the process
		334	receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all
		335	changed/zombie children and call the callback.
		336
		337	Unlike all other callbacks, this callback will be called with an
		338	additional third argument which is the exit status. See the C<waitpid>
		339	function for details.
		340
		341	You can have as many pid watchers per pid as you want.
		342
		343	The C<child_ns> variant doesn't start (activate) the newly created watcher.
		344
		345	=item $w->set ($pid)
		346
		347	Reconfigures the watcher, see the constructor above for details. Can be at
		348	any time.
		349
		350
		351	=item $w = EV::idle $callback
		352
		353	=item $w = EV::idle_ns $callback
		354
		355	Call the callback when there are no pending io, timer/periodic, signal or
		356	child events, i.e. when the process is idle.
		357
		358	The process will not block as long as any idle watchers are active, and
		359	they will be called repeatedly until stopped.
		360
		361	The C<idle_ns> variant doesn't start (activate) the newly created watcher.
		362
		363
		364	=item $w = EV::prepare $callback
		365
		366	=item $w = EV::prepare_ns $callback
		367
		368	Call the callback just before the process would block. You can still
		369	create/modify any watchers at this point.
		370
		371	See the EV::check watcher, below, for explanations and an example.
		372
		373	The C<prepare_ns> variant doesn't start (activate) the newly created watcher.
		374
		375
		376	=item $w = EV::check $callback
		377
		378	=item $w = EV::check_ns $callback
		379
		380	Call the callback just after the process wakes up again (after it has
		381	gathered events), but before any other callbacks have been invoked.
		382
		383	This is used to integrate other event-based software into the EV
		384	mainloop: You register a prepare callback and in there, you create io and
		385	timer watchers as required by the other software. Here is a real-world
		386	example of integrating Net::SNMP (with some details left out):
		387
		388	our @snmp_watcher;
		389
		390	our $snmp_prepare = EV::prepare sub {
		391	# do nothing unless active
		392	$dispatcher->{_event_queue_h}
		393	or return;
		394
		395	# make the dispatcher handle any outstanding stuff
		396
		397	# create an IO watcher for each and every socket
		398	@snmp_watcher = (
		399	(map { EV::io $_, EV::READ, sub { } }
		400	keys %{ $dispatcher->{_descriptors} }),
		401	);
		402
		403	# if there are any timeouts, also create a timer
		404	push @snmp_watcher, EV::timer $event->[Net::SNMP::Dispatcher::_TIME] - EV::now, 0, sub { }
		405	if $event->[Net::SNMP::Dispatcher::_ACTIVE];
		406	};
		407
		408	The callbacks are irrelevant, the only purpose of those watchers is
		409	to wake up the process as soon as one of those events occurs (socket
		410	readable, or timer timed out). The corresponding EV::check watcher will then
		411	clean up:
		412
		413	our $snmp_check = EV::check sub {
		414	# destroy all watchers
		415	@snmp_watcher = ();
		416
		417	# make the dispatcher handle any new stuff
		418	};
		419
		420	The callbacks of the created watchers will not be called as the watchers
		421	are destroyed before this cna happen (remember EV::check gets called
		422	first).
		423
		424	The C<check_ns> variant doesn't start (activate) the newly created watcher.
		425
40	=back	426	=back
41		427
42	=head1 BUGS	428	=head1 THREADS
		429
		430	Threads are not supported by this in any way. Perl pseudo-threads is evil
		431	stuff and must die.
43		432
44	=cut	433	=cut
45		434
46	our $NPRI = 4;	435	our $DIED = sub {
47	our $BASE = init;	436	warn "EV: error in callback (ignoring): $@";
48	priority_init $NPRI;	437	};
		438
		439	init;
		440
		441	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
49		442
50	1;	443	1;
		444
		445	=head1 SEE ALSO
		446
		447	L<EV::DNS>, L<EV::AnyEvent>.
51		448
52	=head1 AUTHOR	449	=head1 AUTHOR
53		450
54	Marc Lehmann <schmorp@schmorp.de>	451	Marc Lehmann <schmorp@schmorp.de>
55	http://home.schmorp.de/	452	http://home.schmorp.de/

Diff Legend

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

Comparing EV/EV.pm (file contents): Revision 1.1 by root, Fri Oct 26 16:50:05 2007 UTC vs. Revision 1.20 by root, Thu Nov 1 17:17:32 2007 UTC

Diff Legend

Comparing EV/EV.pm (file contents):
Revision 1.1 by root, Fri Oct 26 16:50:05 2007 UTC vs.
Revision 1.20 by root, Thu Nov 1 17:17:32 2007 UTC