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

Comparing EV/EV.pm (file contents):
Revision 1.6 by root, Sat Oct 27 07:30:10 2007 UTC vs.
Revision 1.15 by root, Wed Oct 31 18:28:00 2007 UTC

…		…
2		2
3	EV - perl interface to libevent, monkey.org/~provos/libevent/	3	EV - perl interface to libevent, monkey.org/~provos/libevent/
4		4
5	=head1 SYNOPSIS	5	=head1 SYNOPSIS
6		6
7	use EV;	7	use EV;
8		8
9	# TIMER	9	# TIMER
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::timer_abs 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 \| EV::PERSIST, sub {
28	my ($w, $events) = @_; # all callbacks get the watcher object and event mask	28	my ($w, $events) = @_; # all callbacks get the watcher object and event mask
29	if ($events & EV::TIMEOUT) {	29	if ($events & EV::TIMEOUT) {
30	warn "nothign received on stdin for 10 seconds, retrying";	30	warn "nothing received on stdin for 10 seconds, retrying";
31	} else {	31	} else {
32	warn "stdin is readable, you entered: ", <STDIN>;	32	warn "stdin is readable, you entered: ", <STDIN>;
33	}	33	}
34	};	34	};
35	$w->timeout (10);	35	$w->timeout (10);
36		36
		37	my $w = EV::timed_io \*STDIN, EV::READ, 30, sub {
		38	my ($w, $events) = @_;
		39	if ($_[1] & EV::TIMEOUT) {
		40	warn "nothing entered within 30 seconds, bye bye.\n";
		41	$w->stop;
		42	} else {
		43	my $line = <STDIN>;
		44	warn "you entered something, you again have 30 seconds.\n";
		45	}
		46	};
		47
		48	# SIGNALS
		49
		50	my $w = EV::signal 'QUIT', sub {
		51	warn "sigquit received\n";
		52	};
		53
		54	my $w = EV::signal 3, sub {
		55	warn "sigquit received (this is GNU/Linux, right?)\n";
		56	};
		57
37	# MAINLOOP	58	# MAINLOOP
38	EV::dispatch; # loop as long as watchers are active	59	EV::dispatch; # loop as long as watchers are active
39	EV::loop; # the same thing	60	EV::loop; # the same thing
40	EV::loop EV::LOOP_ONCE;	61	EV::loop EV::LOOP_ONCE; # block until some events could be handles
41	EV::loop EV::LOOP_ONSHOT;	62	EV::loop EV::LOOP_NONBLOCK; # check and handle some events, but do not wait
42		63
43	=head1 DESCRIPTION	64	=head1 DESCRIPTION
44		65
45	This module provides an interface to libevent	66	This module provides an interface to libevent
46	(L<http://monkey.org/~provos/libevent/>). You probably should acquaint	67	(L<http://monkey.org/~provos/libevent/>). You probably should acquaint
…		…
55	package EV;	76	package EV;
56		77
57	use strict;	78	use strict;
58		79
59	BEGIN {	80	BEGIN {
60	our $VERSION = '0.01';	81	our $VERSION = '0.03';
61	use XSLoader;	82	use XSLoader;
62	XSLoader::load "EV", $VERSION;	83	XSLoader::load "EV", $VERSION;
63	}	84	}
64		85
65	=head1 FUNCTIONAL INTERFACE	86	@EV::Io::ISA = "EV::Watcher";
		87	@EV::Time::ISA = "EV::Watcher";
		88	@EV::Timer::ISA = "EV::Time";
		89	@EV::Periodic::ISA = "EV::Time";
		90	@EV::Signal::ISA = "EV::Watcher";
		91	@EV::Idle::ISA = "EV::Watcher";
		92	@EV::Prepare::ISA = "EV::Watcher";
		93	@EV::Check::ISA = "EV::Watcher";
		94
		95	=head1 BASIC INTERFACE
66		96
67	=over 4	97	=over 4
68		98
69	=item $EV::NPRI	99	=item $EV::NPRI
70		100
71	How many priority levels are available.	101	How many priority levels are available.
		102
		103	=item $EV::DIED
		104
		105	Must contain a reference to a function that is called when a callback
		106	throws an exception (with $@ containing thr error). The default prints an
		107	informative message and continues.
		108
		109	If this callback throws an exception it will be silently ignored.
72		110
73	=item $time = EV::now	111	=item $time = EV::now
74		112
75	Returns the time in (fractional) seconds since the epoch.	113	Returns the time in (fractional) seconds since the epoch.
76		114
…		…
101		139
102	As long as the returned watcher object is alive, call the C<$callback>	140	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	141	when the events specified in C<$eventmask> happen. Initially, the timeout
104	is disabled.	142	is disabled.
105		143
106	The C<io_ns> variant doesn't add/start the newly created watcher.	144	You can additionall set a timeout to occur on the watcher, but note that
		145	this timeout will not be reset when you get an I/O event in the EV::PERSIST
		146	case, and reaching a timeout will always stop the watcher even in the
		147	EV::PERSIST case.
		148
		149	If you want a timeout to occur only after a specific time of inactivity, set
		150	a repeating timeout and do NOT use EV::PERSIST.
107		151
108	Eventmask can be one or more of these constants ORed together:	152	Eventmask can be one or more of these constants ORed together:
109		153
110	EV::READ wait until read() wouldn't block anymore	154	EV::READ wait until read() wouldn't block anymore
111	EV::WRITE wait until write() wouldn't block anymore	155	EV::WRITE wait until write() wouldn't block anymore
112	EV::PERSIST stay active after an event occured	156	EV::PERSIST stay active after a (non-timeout) event occured
		157
		158	The C<io_ns> variant doesn't add/start the newly created watcher.
		159
		160	=item my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback
		161
		162	=item my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback
		163
		164	Same as C<io> and C<io_ns>, but also specifies a timeout (as if there was
		165	a call to C<< $w->timeout ($timout, 1) >>. The persist flag is not allowed
		166	and will automatically be cleared. The watcher will be restarted after each event.
		167
		168	If the timeout is zero or undef, no timeout will be set, and a normal
		169	watcher (with the persist flag set!) will be created.
		170
		171	This has the effect of timing out after the specified period of inactivity
		172	has happened.
		173
		174	Due to the design of libevent, this is also relatively inefficient, having
		175	one or two io watchers and a separate timeout watcher that you reset on
		176	activity (by calling its C<start> method) is usually more efficient.
113		177
114	=item my $w = EV::timer $after, $repeat, $callback	178	=item my $w = EV::timer $after, $repeat, $callback
115		179
116	=item my $w = EV::timer_ns $after, $repeat, $callback	180	=item my $w = EV::timer_ns $after, $repeat, $callback
117		181
…		…
138		202
139	This can be used to schedule a callback to run at very regular intervals,	203	This can be used to schedule a callback to run at very regular intervals,
140	as long as the processing time is less then the interval (otherwise	204	as long as the processing time is less then the interval (otherwise
141	obviously events will be skipped).	205	obviously events will be skipped).
142		206
		207	Another way to think about it (for the mathematically inclined) is that
		208	C<timer_abs> will try to tun the callback at the next possible time where
		209	C<$time = $at (mod $interval)>, regardless of any time jumps.
		210
143	The C<timer_abs_ns> variant doesn't add/start the newly created watcher.	211	The C<timer_abs_ns> variant doesn't add/start the newly created watcher.
144		212
145	=item my $w = EV::signal $signum, $callback	213	=item my $w = EV::signal $signal, $callback
146		214
147	=item my $w = EV::signal_ns $signum, $callback	215	=item my $w = EV::signal_ns $signal, $callback
148		216
149	Call the callback when signal $signum is received.	217	Call the callback when $signal is received (the signal can be specified
		218	by number or by name, just as with kill or %SIG). Signal watchers are
		219	persistent no natter what.
		220
		221	EV will grab the signal for the process (the kernel only allows one
		222	component to receive signals) when you start a signal watcher, and
		223	removes it again when you stop it. Pelr does the same when you add/remove
		224	callbacks to %SIG, so watch out.
		225
		226	Unfortunately, only one handler can be registered per signal. Screw
		227	libevent.
150		228
151	The C<signal_ns> variant doesn't add/start the newly created watcher.	229	The C<signal_ns> variant doesn't add/start the newly created watcher.
152		230
153	=back	231	=back
154		232
…		…
182		260
183	=item $current_fh = $w->fh	261	=item $current_fh = $w->fh
184		262
185	=item $old_fh = $w->fh ($new_fh)	263	=item $old_fh = $w->fh ($new_fh)
186		264
187	Returns the previously set filehandle and optionally set a new one.	265	Returns the previously set filehandle and optionally set a new one (also
		266	clears the EV::SIGNAL flag when setting a filehandle).
		267
		268	=item $current_signal = $w->signal
		269
		270	=item $old_signal = $w->signal ($new_signal)
		271
		272	Returns the previously set signal number and optionally set a new one (also sets
		273	the EV::SIGNAL flag when setting a signal).
188		274
189	=item $current_eventmask = $w->events	275	=item $current_eventmask = $w->events
190		276
191	=item $old_eventmask = $w->events ($new_eventmask)	277	=item $old_eventmask = $w->events ($new_eventmask)
192		278
…		…
203	=item $w->priority_set ($priority)	289	=item $w->priority_set ($priority)
204		290
205	Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).	291	Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).
206		292
207	=back	293	=back
		294
		295	=head1 THREADS
		296
		297	Threads are not supported by this in any way. Perl pseudo-threads is evil
		298	and must die.
208		299
209	=head1 BUGS	300	=head1 BUGS
210		301
211	Lots. Libevent itself isn't well tested and rather buggy, and this module	302	Lots. Libevent itself isn't well tested and rather buggy, and this module
212	is quite new at the moment.	303	is quite new at the moment.
213		304
214	Please note that the epoll method is not, in general, reliable in	305	Please note that the epoll method is not, in general, reliable in programs
215	programs that use fork (even if no libveent calls are being made in the	306	that use fork (even if no libveent calls are being made in the forked
216	forked process). Since this is such a common issue, this module will	307	process). If your program behaves erratically, try setting the environment
217	force the epoll method in EV to be off unless the global variable	308	variable C<EVENT_NOEPOLL> first when running the program.
218	$EV::ENABLE_EPOLL is set to 1 before loading this module for the first	309
219	time.	310	In general, if you fork, then you can only use the EV module in one of the
		311	children.
220		312
221	=cut	313	=cut
222		314
223	our $NPRI = 4;	315	our $DIED = sub {
224	our $BASE;	316	warn "EV: error in callback (ignoring): $@";
225	our $ENABLE_EPOLL;	317	};
226		318
227	{	319	init;
228	local $ENV{EVENT_NOEPOLL};
229	$ENV{EVENT_NOEPOLL} = 1 unless $ENABLE_EPOLL;
230	$BASE = init;
231	}
232
233	priority_init $NPRI;
234		320
235	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];	321	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
236		322
237	1;	323	1;
238		324

Diff Legend

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

Comparing EV/EV.pm (file contents): Revision 1.6 by root, Sat Oct 27 07:30:10 2007 UTC vs. Revision 1.15 by root, Wed Oct 31 18:28:00 2007 UTC

Diff Legend

Comparing EV/EV.pm (file contents):
Revision 1.6 by root, Sat Oct 27 07:30:10 2007 UTC vs.
Revision 1.15 by root, Wed Oct 31 18:28:00 2007 UTC