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