[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.10 by root, Mon Oct 29 07:24:37 2007 UTC

…		…
4		4
5	=head1 SYNOPSIS	5	=head1 SYNOPSIS
6		6
7	use EV;	7	use EV;
8		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 "nothing 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
9	=head1 DESCRIPTION	43	=head1 DESCRIPTION
10		44
11	This module provides an interface to libevent	45	This module provides an interface to libevent
12	(L<http://monkey.org/~provos/libevent/>).	46	(L<http://monkey.org/~provos/libevent/>). You probably should acquaint
		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.
13		52
14	=cut	53	=cut
15		54
16	package EV;	55	package EV;
17		56
18	use strict;	57	use strict;
19		58
20	BEGIN {	59	BEGIN {
21	our $VERSION = '0.01';	60	our $VERSION = '0.02';
22	use XSLoader;	61	use XSLoader;
23	XSLoader::load "EV", $VERSION;	62	XSLoader::load "EV", $VERSION;
24	}	63	}
25		64
26	=head1 FUNCTIONAL INTERFACE	65	=head1 BASIC INTERFACE
27		66
28	=over 4	67	=over 4
29		68
		69	=item $EV::NPRI
		70
		71	How many priority levels are available.
		72
		73	=item $EV::DIED
		74
		75	Must contain a reference to a function that is called when a callback
		76	throws an exception (with $@ containing thr error). The default prints an
		77	informative message and continues.
		78
		79	If this callback throws an exception it will be silently ignored.
		80
		81	=item $time = EV::now
		82
		83	Returns the time in (fractional) seconds since the epoch.
		84
		85	=item $version = EV::version
		86
		87	=item $method = EV::method
		88
		89	Return version string and event polling method used.
		90
		91	=item EV::loop $flags # EV::LOOP_ONCE, EV::LOOP_ONESHOT
		92
		93	=item EV::loopexit $after
		94
		95	Exit any active loop or dispatch after C<$after> seconds or immediately if
		96	C<$after> is missing or zero.
		97
		98	=item EV::dispatch
		99
		100	Same as C<EV::loop 0>.
		101
		102	=item EV::event $callback
		103
		104	Creates a new event watcher waiting for nothing, calling the given callback.
		105
		106	=item my $w = EV::io $fileno_or_fh, $eventmask, $callback
		107
		108	=item my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
		109
		110	As long as the returned watcher object is alive, call the C<$callback>
		111	when the events specified in C<$eventmask> happen. Initially, the timeout
		112	is disabled.
		113
		114	You can additionall set a timeout to occur on the watcher, but note that
		115	this timeout will not be reset when you get an I/O event in the EV::PERSIST
		116	case, and reaching a timeout will always stop the watcher even in the
		117	EV::PERSIST case.
		118
		119	If you want a timeout to occur only after a specific time of inactivity, set
		120	a repeating timeout and do NOT use EV::PERSIST.
		121
		122	Eventmask can be one or more of these constants ORed together:
		123
		124	EV::READ wait until read() wouldn't block anymore
		125	EV::WRITE wait until write() wouldn't block anymore
		126	EV::PERSIST stay active after a (non-timeout) event occured
		127
		128	The C<io_ns> variant doesn't add/start the newly created watcher.
		129
		130	=item my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback
		131
		132	=item my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback
		133
		134	Same as C<io> and C<io_ns>, but also specifies a timeout (as if there was
		135	a call to C<< $w->timeout ($timout, 1) >>. The persist flag is not allowed
		136	and will automatically be cleared. The watcher will be restarted after each event.
		137
		138	If the timeout is zero or undef, no timeout will be set, and a normal
		139	watcher (with the persist flag set!) will be created.
		140
		141	This has the effect of timing out after the specified period of inactivity
		142	has happened.
		143
		144	Due to the design of libevent, this is also relatively inefficient, having
		145	one or two io watchers and a separate timeout watcher that you reset on
		146	activity (by calling its C<start> method) is usually more efficient.
		147
		148	=item my $w = EV::timer $after, $repeat, $callback
		149
		150	=item my $w = EV::timer_ns $after, $repeat, $callback
		151
		152	Calls the callback after C<$after> seconds. If C<$repeat> is true, the
		153	timer will be restarted after the callback returns. This means that the
		154	callback would be called roughly every C<$after> seconds, prolonged by the
		155	time the callback takes.
		156
		157	The C<timer_ns> variant doesn't add/start the newly created watcher.
		158
		159	=item my $w = EV::timer_abs $at, $interval, $callback
		160
		161	=item my $w = EV::timer_abs_ns $at, $interval, $callback
		162
		163	Similar to EV::timer, but the time is given as an absolute point in time
		164	(C<$at>), plus an optional C<$interval>.
		165
		166	If the C<$interval> is zero, then the callback will be called at the time
		167	C<$at> if that is in the future, or as soon as possible if its in the
		168	past. It will not automatically repeat.
		169
		170	If the C<$interval> is nonzero, then the watcher will always be scheduled
		171	to time out at the next C<$at + integer * $interval> time.
		172
		173	This can be used to schedule a callback to run at very regular intervals,
		174	as long as the processing time is less then the interval (otherwise
		175	obviously events will be skipped).
		176
		177	Another way to think about it (for the mathematically inclined) is that
		178	C<timer_abs> will try to tun the callback at the next possible time where
		179	C<$time = $at (mod $interval)>, regardless of any time jumps.
		180
		181	The C<timer_abs_ns> variant doesn't add/start the newly created watcher.
		182
		183	=item my $w = EV::signal $signum, $callback
		184
		185	=item my $w = EV::signal_ns $signum, $callback
		186
		187	Call the callback when signal $signum is received.
		188
		189	The C<signal_ns> variant doesn't add/start the newly created watcher.
		190
30	=back	191	=back
31		192
		193	=head1 THE EV::Event CLASS
32		194
33	=head1 OBJECT-ORIENTED INTERFACE	195	All EV functions creating an event watcher (designated by C<my $w =>
34		196	above) support the following methods on the returned watcher object:
35	The object oriented interface lets you configure your own encoding or
36	decoding style, within the limits of supported formats.
37		197
38	=over 4	198	=over 4
39		199
		200	=item $w->add ($timeout)
		201
		202	Stops and (re-)starts the event watcher, setting the optional timeout to
		203	the given value, or clearing the timeout if none is given.
		204
		205	=item $w->start
		206
		207	Stops and (re-)starts the event watcher without touching the timeout.
		208
		209	=item $w->del
		210
		211	=item $w->stop
		212
		213	Stop the event watcher if it was started.
		214
		215	=item $current_callback = $w->cb
		216
		217	=item $old_callback = $w->cb ($new_callback)
		218
		219	Return the previously set callback and optionally set a new one.
		220
		221	=item $current_fh = $w->fh
		222
		223	=item $old_fh = $w->fh ($new_fh)
		224
		225	Returns the previously set filehandle and optionally set a new one (also
		226	clears the EV::SIGNAL flag when setting a filehandle).
		227
		228	=item $current_signal = $w->signal
		229
		230	=item $old_signal = $w->signal ($new_signal)
		231
		232	Returns the previously set signal number and optionally set a new one (also sets
		233	the EV::SIGNAL flag when setting a signal).
		234
		235	=item $current_eventmask = $w->events
		236
		237	=item $old_eventmask = $w->events ($new_eventmask)
		238
		239	Returns the previously set event mask and optionally set a new one.
		240
		241	=item $w->timeout ($after, $repeat)
		242
		243	Resets the timeout (see C<EV::timer> for details).
		244
		245	=item $w->timeout_abs ($at, $interval)
		246
		247	Resets the timeout (see C<EV::timer_abs> for details).
		248
		249	=item $w->priority_set ($priority)
		250
		251	Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).
		252
40	=back	253	=back
41		254
42	=head1 BUGS	255	=head1 BUGS
43		256
		257	Lots. Libevent itself isn't well tested and rather buggy, and this module
		258	is quite new at the moment.
		259
		260	Please note that the epoll method is not, in general, reliable in programs
		261	that use fork (even if no libveent calls are being made in the forked
		262	process). If your program behaves erratically, try setting the environment
		263	variable C<EVENT_NOEPOLL> first when running the program.
		264
		265	In general, if you fork, then you can only use the EV module in one of the
		266	children.
		267
44	=cut	268	=cut
		269
		270	our $DIED = sub {
		271	warn "EV: error in callback (ignoring): $@";
		272	};
45		273
46	our $NPRI = 4;	274	our $NPRI = 4;
47	our $BASE = init;	275	our $BASE = init;
48	priority_init $NPRI;	276	priority_init $NPRI;
49		277
		278	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
		279
50	1;	280	1;
		281
		282	=head1 SEE ALSO
		283
		284	L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
		285	L<EV::AnyEvent>.
51		286
52	=head1 AUTHOR	287	=head1 AUTHOR
53		288
54	Marc Lehmann <schmorp@schmorp.de>	289	Marc Lehmann <schmorp@schmorp.de>
55	http://home.schmorp.de/	290	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.10 by root, Mon Oct 29 07:24:37 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.10 by root, Mon Oct 29 07:24:37 2007 UTC