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

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.16 by root, Wed Oct 31 20:10:17 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.16 by root, Wed Oct 31 20:10:17 2007 UTC