[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.14 by root, Wed Oct 31 10:53:53 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	=head1 BASIC INTERFACE
66		87
67	=over 4	88	=over 4
68		89
69	=item $EV::NPRI	90	=item $EV::NPRI
70		91
71	How many priority levels are available.	92	How many priority levels are available.
		93
		94	=item $EV::DIED
		95
		96	Must contain a reference to a function that is called when a callback
		97	throws an exception (with $@ containing thr error). The default prints an
		98	informative message and continues.
		99
		100	If this callback throws an exception it will be silently ignored.
72		101
73	=item $time = EV::now	102	=item $time = EV::now
74		103
75	Returns the time in (fractional) seconds since the epoch.	104	Returns the time in (fractional) seconds since the epoch.
76		105
…		…
101		130
102	As long as the returned watcher object is alive, call the C<$callback>	131	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	132	when the events specified in C<$eventmask> happen. Initially, the timeout
104	is disabled.	133	is disabled.
105		134
106	The C<io_ns> variant doesn't add/start the newly created watcher.	135	You can additionall set a timeout to occur on the watcher, but note that
		136	this timeout will not be reset when you get an I/O event in the EV::PERSIST
		137	case, and reaching a timeout will always stop the watcher even in the
		138	EV::PERSIST case.
		139
		140	If you want a timeout to occur only after a specific time of inactivity, set
		141	a repeating timeout and do NOT use EV::PERSIST.
107		142
108	Eventmask can be one or more of these constants ORed together:	143	Eventmask can be one or more of these constants ORed together:
109		144
110	EV::READ wait until read() wouldn't block anymore	145	EV::READ wait until read() wouldn't block anymore
111	EV::WRITE wait until write() wouldn't block anymore	146	EV::WRITE wait until write() wouldn't block anymore
112	EV::PERSIST stay active after an event occured	147	EV::PERSIST stay active after a (non-timeout) event occured
		148
		149	The C<io_ns> variant doesn't add/start the newly created watcher.
		150
		151	=item my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback
		152
		153	=item my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback
		154
		155	Same as C<io> and C<io_ns>, but also specifies a timeout (as if there was
		156	a call to C<< $w->timeout ($timout, 1) >>. The persist flag is not allowed
		157	and will automatically be cleared. The watcher will be restarted after each event.
		158
		159	If the timeout is zero or undef, no timeout will be set, and a normal
		160	watcher (with the persist flag set!) will be created.
		161
		162	This has the effect of timing out after the specified period of inactivity
		163	has happened.
		164
		165	Due to the design of libevent, this is also relatively inefficient, having
		166	one or two io watchers and a separate timeout watcher that you reset on
		167	activity (by calling its C<start> method) is usually more efficient.
113		168
114	=item my $w = EV::timer $after, $repeat, $callback	169	=item my $w = EV::timer $after, $repeat, $callback
115		170
116	=item my $w = EV::timer_ns $after, $repeat, $callback	171	=item my $w = EV::timer_ns $after, $repeat, $callback
117		172
…		…
138		193
139	This can be used to schedule a callback to run at very regular intervals,	194	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	195	as long as the processing time is less then the interval (otherwise
141	obviously events will be skipped).	196	obviously events will be skipped).
142		197
		198	Another way to think about it (for the mathematically inclined) is that
		199	C<timer_abs> will try to tun the callback at the next possible time where
		200	C<$time = $at (mod $interval)>, regardless of any time jumps.
		201
143	The C<timer_abs_ns> variant doesn't add/start the newly created watcher.	202	The C<timer_abs_ns> variant doesn't add/start the newly created watcher.
144		203
145	=item my $w = EV::signal $signum, $callback	204	=item my $w = EV::signal $signal, $callback
146		205
147	=item my $w = EV::signal_ns $signum, $callback	206	=item my $w = EV::signal_ns $signal, $callback
148		207
149	Call the callback when signal $signum is received.	208	Call the callback when $signal is received (the signal can be specified
		209	by number or by name, just as with kill or %SIG). Signal watchers are
		210	persistent no natter what.
		211
		212	EV will grab the signal for the process (the kernel only allows one
		213	component to receive signals) when you start a signal watcher, and
		214	removes it again when you stop it. Pelr does the same when you add/remove
		215	callbacks to %SIG, so watch out.
		216
		217	Unfortunately, only one handler can be registered per signal. Screw
		218	libevent.
150		219
151	The C<signal_ns> variant doesn't add/start the newly created watcher.	220	The C<signal_ns> variant doesn't add/start the newly created watcher.
152		221
153	=back	222	=back
154		223
…		…
182		251
183	=item $current_fh = $w->fh	252	=item $current_fh = $w->fh
184		253
185	=item $old_fh = $w->fh ($new_fh)	254	=item $old_fh = $w->fh ($new_fh)
186		255
187	Returns the previously set filehandle and optionally set a new one.	256	Returns the previously set filehandle and optionally set a new one (also
		257	clears the EV::SIGNAL flag when setting a filehandle).
		258
		259	=item $current_signal = $w->signal
		260
		261	=item $old_signal = $w->signal ($new_signal)
		262
		263	Returns the previously set signal number and optionally set a new one (also sets
		264	the EV::SIGNAL flag when setting a signal).
188		265
189	=item $current_eventmask = $w->events	266	=item $current_eventmask = $w->events
190		267
191	=item $old_eventmask = $w->events ($new_eventmask)	268	=item $old_eventmask = $w->events ($new_eventmask)
192		269
…		…
203	=item $w->priority_set ($priority)	280	=item $w->priority_set ($priority)
204		281
205	Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).	282	Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).
206		283
207	=back	284	=back
		285
		286	=head1 THREADS
		287
		288	Threads are not supported by this in any way. Perl pseudo-threads is evil
		289	and must die.
208		290
209	=head1 BUGS	291	=head1 BUGS
210		292
211	Lots. Libevent itself isn't well tested and rather buggy, and this module	293	Lots. Libevent itself isn't well tested and rather buggy, and this module
212	is quite new at the moment.	294	is quite new at the moment.
213		295
214	Please note that the epoll method is not, in general, reliable in	296	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	297	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	298	process). If your program behaves erratically, try setting the environment
217	force the epoll method in EV to be off unless the global variable	299	variable C<EVENT_NOEPOLL> first when running the program.
218	$EV::ENABLE_EPOLL is set to 1 before loading this module for the first	300
219	time.	301	In general, if you fork, then you can only use the EV module in one of the
		302	children.
220		303
221	=cut	304	=cut
222		305
223	our $NPRI = 4;	306	our $DIED = sub {
224	our $BASE;	307	warn "EV: error in callback (ignoring): $@";
225	our $ENABLE_EPOLL;	308	};
226		309
227	{	310	init;
228	local $ENV{EVENT_NOEPOLL};
229	$ENV{EVENT_NOEPOLL} = 1 unless $ENABLE_EPOLL;
230	$BASE = init;
231	}
232
233	priority_init $NPRI;
234		311
235	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];	312	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
236		313
237	1;	314	1;
238		315

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.14 by root, Wed Oct 31 10:53:53 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.14 by root, Wed Oct 31 10:53:53 2007 UTC