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

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.17 by root, Wed Oct 31 21:34:45 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.17 by root, Wed Oct 31 21:34:45 2007 UTC