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

Comparing EV/EV.pm (file contents):
Revision 1.20 by root, Thu Nov 1 17:17:32 2007 UTC vs.
Revision 1.30 by root, Thu Nov 8 02:19:36 2007 UTC

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

Diff Legend

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

Comparing EV/EV.pm (file contents): Revision 1.20 by root, Thu Nov 1 17:17:32 2007 UTC vs. Revision 1.30 by root, Thu Nov 8 02:19:36 2007 UTC

Diff Legend

Comparing EV/EV.pm (file contents):
Revision 1.20 by root, Thu Nov 1 17:17:32 2007 UTC vs.
Revision 1.30 by root, Thu Nov 8 02:19:36 2007 UTC