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

Comparing EV/EV.pm (file contents):
Revision 1.22 by root, Fri Nov 2 11:02:22 2007 UTC vs.
Revision 1.37 by root, Mon Nov 12 07:58:52 2007 UTC

…		…
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, 2, sub {
16	warn "is called roughly every 2s (repeat = 1)";	16	warn "is called roughly every 2s (repeat = 2)";
17	};	17	};
18		18
19	undef $w; # destroy event watcher again	19	undef $w; # destroy event watcher again
20		20
21	my $w = EV::periodic 0, 60, sub {	21	my $w = EV::periodic 0, 60, 0, sub {
22	warn "is called every minute, on the minute, exactly";	22	warn "is called every minute, on the minute, exactly";
23	};	23	};
24		24
25	# IO	25	# IO
26		26
27	my $w = EV::io *STDIN, EV::READ, sub {	27	my $w = EV::io *STDIN, EV::READ, sub {
28	my ($w, $revents) = @_; # all callbacks get the watcher object and event mask	28	my ($w, $revents) = @_; # all callbacks receive the watcher and event mask
29	warn "stdin is readable, you entered: ", <STDIN>;	29	warn "stdin is readable, you entered: ", <STDIN>;
30	};	30	};
31		31
32	# SIGNALS	32	# SIGNALS
33		33
34	my $w = EV::signal 'QUIT', sub {	34	my $w = EV::signal 'QUIT', sub {
35	warn "sigquit received\n";	35	warn "sigquit received\n";
36	};	36	};
37		37
38	my $w = EV::signal 3, sub {
39	warn "sigquit received (this is GNU/Linux, right?)\n";
40	};
41
42	# CHILD/PID STATUS CHANGES	38	# CHILD/PID STATUS CHANGES
43		39
44	my $w = EV::child 666, sub {	40	my $w = EV::child 666, sub {
45	my ($w, $revents, $status) = @_;	41	my ($w, $revents) = @_;
		42	my $status = $w->rstatus;
46	};	43	};
47		44
48	# MAINLOOP	45	# MAINLOOP
49	EV::loop; # loop until EV::loop_done is called	46	EV::loop; # loop until EV::loop_done is called or all watchers stop
50	EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled	47	EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled
51	EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block	48	EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
52		49
53	=head1 DESCRIPTION	50	=head1 DESCRIPTION
54		51
…		…
60	package EV;	57	package EV;
61		58
62	use strict;	59	use strict;
63		60
64	BEGIN {	61	BEGIN {
65	our $VERSION = '0.1';	62	our $VERSION = '0.8';
66	use XSLoader;	63	use XSLoader;
67	XSLoader::load "EV", $VERSION;	64	XSLoader::load "EV", $VERSION;
68	}	65	}
69		66
70	@EV::Io::ISA =	67	@EV::Io::ISA =
…		…
150	In the rare case where one wants to create a watcher but not start it at	147	In the rare case where one wants to create a watcher but not start it at
151	the same time, each constructor has a variant with a trailing C<_ns> in	148	the same time, each constructor has a variant with a trailing C<_ns> in
152	its name, e.g. EV::io has a non-starting variant EV::io_ns and so on.	149	its name, e.g. EV::io has a non-starting variant EV::io_ns and so on.
153		150
154	Please note that a watcher will automatically be stopped when the watcher	151	Please note that a watcher will automatically be stopped when the watcher
155	object is returned, so you I<need> to keep the watcher objects returned by	152	object is destroyed, so you I<need> to keep the watcher objects returned by
156	the constructors.	153	the constructors.
		154
		155	Also, all methods changing some aspect of a watcher (->set, ->priority,
		156	->fh and so on) automatically stop and start it again if it is active,
		157	which means pending events get lost.
157		158
158	=head2 WATCHER TYPES	159	=head2 WATCHER TYPES
159		160
160	Now lets move to the existing watcher types and asociated methods.	161	Now lets move to the existing watcher types and asociated methods.
161		162
…		…
180		181
181	=item $bool = $w->is_active	182	=item $bool = $w->is_active
182		183
183	Returns true if the watcher is active, false otherwise.	184	Returns true if the watcher is active, false otherwise.
184		185
		186	=item $current_data = $w->data
		187
		188	=item $old_data = $w->data ($new_data)
		189
		190	Queries a freely usable data scalar on the watcher and optionally changes
		191	it. This is a way to associate custom data with a watcher:
		192
		193	my $w = EV::timer 60, 0, sub {
		194	warn $_[0]->data;
		195	};
		196	$w->data ("print me!");
		197
185	=item $current_cb = $w->cb	198	=item $current_cb = $w->cb
186		199
187	=item $old_cb = $w->cb ($new_cb)	200	=item $old_cb = $w->cb ($new_cb)
188		201
189	Queries the callback on the watcher and optionally changes it. You cna do	202	Queries the callback on the watcher and optionally changes it. You can do
190	this at any time.	203	this at any time without the watcher restarting.
		204
		205	=item $current_priority = $w->priority
		206
		207	=item $old_priority = $w->priority ($new_priority)
		208
		209	Queries the priority on the watcher and optionally changes it. Pending
		210	watchers with higher priority will be invoked first. The valid range of
		211	priorities lies between EV::MAXPRI (default 2) and EV::MINPRI (default
		212	-2). If the priority is outside this range it will automatically be
		213	normalised to the nearest valid priority.
		214
		215	The default priority of any newly-created weatcher is 0.
191		216
192	=item $w->trigger ($revents)	217	=item $w->trigger ($revents)
193		218
194	Call the callback now with the given event mask.	219	Call the callback now with the given event mask.
195		220
…		…
267	operation. You create a timer object with the same value for C<$after> and	292	operation. You create a timer object with the same value for C<$after> and
268	C<$repeat>, and then, in the read/write watcher, run the C<again> method	293	C<$repeat>, and then, in the read/write watcher, run the C<again> method
269	on the timeout.	294	on the timeout.
270		295
271		296
272	=item $w = EV::periodic $at, $interval, $callback	297	=item $w = EV::periodic $at, $interval, $reschedule_cb, $callback
273		298
274	=item $w = EV::periodic_ns $at, $interval, $callback	299	=item $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
275		300
276	Similar to EV::timer, but the time is given as an absolute point in time	301	Similar to EV::timer, but is not based on relative timeouts but on
277	(C<$at>), plus an optional C<$interval>.	302	absolute times. Apart from creating "simple" timers that trigger "at" the
		303	specified time, it can also be used for non-drifting absolute timers and
		304	more complex, cron-like, setups that are not adversely affected by time
		305	jumps (i.e. when the system clock is changed by explicit date -s or other
		306	means such as ntpd). It is also the most complex watcher type in EV.
278		307
279	If the C<$interval> is zero, then the callback will be called at the time	308	It has three distinct "modes":
280	C<$at> if that is in the future, or as soon as possible if it is in the
281	past. It will not automatically repeat.
282		309
283	If the C<$interval> is nonzero, then the watcher will always be scheduled	310	=over 4
284	to time out at the next C<$at + N * $interval> time.
285		311
286	This can be used to schedule a callback to run at very regular intervals,	312	=item * absolute timer ($interval = $reschedule_cb = 0)
287	as long as the processing time is less then the interval (otherwise	313
288	obviously events will be skipped).	314	This time simply fires at the wallclock time C<$at> and doesn't repeat. It
		315	will not adjust when a time jump occurs, that is, if it is to be run
		316	at January 1st 2011 then it will run when the system time reaches or
		317	surpasses this time.
		318
		319	=item * non-repeating interval timer ($interval > 0, $reschedule_cb = 0)
		320
		321	In this mode the watcher will always be scheduled to time out at the
		322	next C<$at + N * $interval> time (for some integer N) and then repeat,
		323	regardless of any time jumps.
		324
		325	This can be used to create timers that do not drift with respect to system
		326	time:
		327
		328	my $hourly = EV::periodic 0, 3600, 0, sub { print "once/hour\n" };
		329
		330	That doesn't mean there will always be 3600 seconds in between triggers,
		331	but only that the the clalback will be called when the system time shows a
		332	full hour (UTC).
289		333
290	Another way to think about it (for the mathematically inclined) is that	334	Another way to think about it (for the mathematically inclined) is that
291	EV::periodic will try to run the callback at the next possible time where	335	EV::periodic will try to run the callback in this mode at the next
292	C<$time = $at (mod $interval)>, regardless of any time jumps.	336	possible time where C<$time = $at (mod $interval)>, regardless of any time
		337	jumps.
293		338
294	This periodic timer is based on "wallclock time", that is, if the clock	339	=item * manual reschedule mode ($reschedule_cb = coderef)
295	changes (C<ntp>, C<date -s> etc.), then the timer will nevertheless run at	340
296	the specified time. This means it will never drift (it might jitter, but	341	In this mode $interval and $at are both being ignored. Instead, each
297	it will not drift).	342	time the periodic watcher gets scheduled, the reschedule callback
		343	($reschedule_cb) will be called with the watcher as first, and the current
		344	time as second argument.
		345
		346	I<This callback MUST NOT stop or destroy this or any other periodic
		347	watcher, ever>. If you need to stop it, return 1e30 and stop it
		348	afterwards.
		349
		350	It must return the next time to trigger, based on the passed time value
		351	(that is, the lowest time value larger than to the second argument). It
		352	will usually be called just before the callback will be triggered, but
		353	might be called at other times, too.
		354
		355	This can be used to create very complex timers, such as a timer that
		356	triggers on each midnight, local time (actually 24 hours after the last
		357	midnight, to keep the example simple. If you know a way to do it correctly
		358	in about the same space (without requiring elaborate modules), drop me a
		359	note :):
		360
		361	my $daily = EV::periodic 0, 0, sub {
		362	my ($w, $now) = @_;
		363
		364	use Time::Local ();
		365	my (undef, undef, undef, $d, $m, $y) = localtime $now;
		366	86400 + Time::Local::timelocal 0, 0, 0, $d, $m, $y
		367	}, sub {
		368	print "it's midnight or likely shortly after, now\n";
		369	};
		370
		371	=back
298		372
299	The C<periodic_ns> variant doesn't start (activate) the newly created watcher.	373	The C<periodic_ns> variant doesn't start (activate) the newly created watcher.
300		374
301	=item $w->set ($at, $interval)	375	=item $w->set ($at, $interval, $reschedule_cb)
302		376
303	Reconfigures the watcher, see the constructor above for details. Can be at	377	Reconfigures the watcher, see the constructor above for details. Can be at
304	any time.	378	any time.
		379
		380	=item $w->again
		381
		382	Simply stops and starts the watcher again.
305		383
306		384
307	=item $w = EV::signal $signal, $callback	385	=item $w = EV::signal $signal, $callback
308		386
309	=item $w = EV::signal_ns $signal, $callback	387	=item $w = EV::signal_ns $signal, $callback
…		…
340	Call the callback when a status change for pid C<$pid> (or any pid	418	Call the callback when a status change for pid C<$pid> (or any pid
341	if C<$pid> is 0) has been received. More precisely: when the process	419	if C<$pid> is 0) has been received. More precisely: when the process
342	receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all	420	receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all
343	changed/zombie children and call the callback.	421	changed/zombie children and call the callback.
344		422
345	Unlike all other callbacks, this callback will be called with an	423	You can access both status and pid by using the C<rstatus> and C<rpid>
346	additional third argument which is the exit status. See the C<waitpid>	424	methods on the watcher object.
347	function for details.
348		425
349	You can have as many pid watchers per pid as you want.	426	You can have as many pid watchers per pid as you want.
350		427
351	The C<child_ns> variant doesn't start (activate) the newly created watcher.	428	The C<child_ns> variant doesn't start (activate) the newly created watcher.
352		429
…		…
358	=item $current_pid = $w->pid	435	=item $current_pid = $w->pid
359		436
360	=item $old_pid = $w->pid ($new_pid)	437	=item $old_pid = $w->pid ($new_pid)
361		438
362	Returns the previously set process id and optionally set a new one.	439	Returns the previously set process id and optionally set a new one.
		440
		441	=item $exit_status = $w->rstatus
		442
		443	Return the exit/wait status (as returned by waitpid, see the waitpid entry
		444	in perlfunc).
		445
		446	=item $pid = $w->rpid
		447
		448	Return the pid of the awaited child (useful when you have installed a
		449	watcher for all pids).
363		450
364		451
365	=item $w = EV::idle $callback	452	=item $w = EV::idle $callback
366		453
367	=item $w = EV::idle_ns $callback	454	=item $w = EV::idle_ns $callback
…		…
448		535
449	our $DIED = sub {	536	our $DIED = sub {
450	warn "EV: error in callback (ignoring): $@";	537	warn "EV: error in callback (ignoring): $@";
451	};	538	};
452		539
453	init;	540	default_loop
454		541	or die 'EV: cannot initialise libev backend. bad $ENV{LIBEV_METHODS}?';
455	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
456		542
457	1;	543	1;
458		544
459	=head1 SEE ALSO	545	=head1 SEE ALSO
460		546

Diff Legend

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

Comparing EV/EV.pm (file contents): Revision 1.22 by root, Fri Nov 2 11:02:22 2007 UTC vs. Revision 1.37 by root, Mon Nov 12 07:58:52 2007 UTC

Diff Legend

Comparing EV/EV.pm (file contents):
Revision 1.22 by root, Fri Nov 2 11:02:22 2007 UTC vs.
Revision 1.37 by root, Mon Nov 12 07:58:52 2007 UTC