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

Comparing EV/EV.pm (file contents):
Revision 1.21 by root, Thu Nov 1 17:20:25 2007 UTC vs.
Revision 1.33 by root, Fri Nov 9 19:33:51 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.6';
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. This means it will never drift (it might jitter, but	346	In this mode $interval and $at are both being ignored. Instead, each time
297	it will not drift).	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 this or any other periodic
		352	watcher, ever>. If you need to stop it, return 1e30 and stop it
		353	afterwards.
		354
		355	It must return the next time to trigger, based on the passed time value
		356	(that is, the lowest time value larger than to the second argument). It
		357	will usually be called just before the callback will be triggered, but
		358	might be called at other times, too.
		359
		360	This can be used to create very complex timers, such as a timer that
		361	triggers on each midnight, local time (actually 24 hours after the last
		362	midnight, to keep the example simple. If you know a way to do it correctly
		363	in about the same space (without requiring elaborate modules), drop me a
		364	note :):
		365
		366	my $daily = EV::periodic 0, 0, sub {
		367	my ($w, $now) = @_;
		368
		369	use Time::Local ();
		370	my (undef, undef, undef, $d, $m, $y) = localtime $now;
		371	86400 + Time::Local::timelocal 0, 0, 0, $d, $m, $y
		372	}, sub {
		373	print "it's midnight or likely shortly after, now\n";
		374	};
		375
		376	=back
298		377
299	The C<periodic_ns> variant doesn't start (activate) the newly created watcher.	378	The C<periodic_ns> variant doesn't start (activate) the newly created watcher.
300		379
301	=item $w->set ($at, $interval)	380	=item $w->set ($at, $interval, $reschedule_cb)
302		381
303	Reconfigures the watcher, see the constructor above for details. Can be at	382	Reconfigures the watcher, see the constructor above for details. Can be at
304	any time.	383	any time.
		384
		385	=item $w->again
		386
		387	Simply stops and starts the watcher again.
305		388
306		389
307	=item $w = EV::signal $signal, $callback	390	=item $w = EV::signal $signal, $callback
308		391
309	=item $w = EV::signal_ns $signal, $callback	392	=item $w = EV::signal_ns $signal, $callback
…		…
323	=item $w->set ($signal)	406	=item $w->set ($signal)
324		407
325	Reconfigures the watcher, see the constructor above for details. Can be at	408	Reconfigures the watcher, see the constructor above for details. Can be at
326	any time.	409	any time.
327		410
		411	=item $current_signum = $w->signal
		412
		413	=item $old_signum = $w->signal ($new_signal)
		414
		415	Returns the previously set signal (always as a number not name) and
		416	optionally set a new one.
		417
328		418
329	=item $w = EV::child $pid, $callback	419	=item $w = EV::child $pid, $callback
330		420
331	=item $w = EV::child_ns $pid, $callback	421	=item $w = EV::child_ns $pid, $callback
332		422
333	Call the callback when a status change for pid C<$pid> (or any pid	423	Call the callback when a status change for pid C<$pid> (or any pid
334	if C<$pid> is 0) has been received. More precisely: when the process	424	if C<$pid> is 0) has been received. More precisely: when the process
335	receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all	425	receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all
336	changed/zombie children and call the callback.	426	changed/zombie children and call the callback.
337		427
338	Unlike all other callbacks, this callback will be called with an	428	You can access both status and pid by using the C<rstatus> and C<rpid>
339	additional third argument which is the exit status. See the C<waitpid>	429	methods on the watcher object.
340	function for details.
341		430
342	You can have as many pid watchers per pid as you want.	431	You can have as many pid watchers per pid as you want.
343		432
344	The C<child_ns> variant doesn't start (activate) the newly created watcher.	433	The C<child_ns> variant doesn't start (activate) the newly created watcher.
345		434
346	=item $w->set ($pid)	435	=item $w->set ($pid)
347		436
348	Reconfigures the watcher, see the constructor above for details. Can be at	437	Reconfigures the watcher, see the constructor above for details. Can be at
349	any time.	438	any time.
		439
		440	=item $current_pid = $w->pid
		441
		442	=item $old_pid = $w->pid ($new_pid)
		443
		444	Returns the previously set process id and optionally set a new one.
		445
		446	=item $exit_status = $w->rstatus
		447
		448	Return the exit/wait status (as returned by waitpid, see the waitpid entry
		449	in perlfunc).
		450
		451	=item $pid = $w->rpid
		452
		453	Return the pid of the awaited child (useful when you have installed a
		454	watcher for all pids).
350		455
351		456
352	=item $w = EV::idle $callback	457	=item $w = EV::idle $callback
353		458
354	=item $w = EV::idle_ns $callback	459	=item $w = EV::idle_ns $callback
…		…
435		540
436	our $DIED = sub {	541	our $DIED = sub {
437	warn "EV: error in callback (ignoring): $@";	542	warn "EV: error in callback (ignoring): $@";
438	};	543	};
439		544
440	init;	545	default_loop
441		546	or die 'EV: cannot initialise libev backend. bad $ENV{LIBEV_METHODS}?';
442	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
443		547
444	1;	548	1;
445		549
446	=head1 SEE ALSO	550	=head1 SEE ALSO
447		551

Diff Legend

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

Comparing EV/EV.pm (file contents): Revision 1.21 by root, Thu Nov 1 17:20:25 2007 UTC vs. Revision 1.33 by root, Fri Nov 9 19:33:51 2007 UTC

Diff Legend

Comparing EV/EV.pm (file contents):
Revision 1.21 by root, Thu Nov 1 17:20:25 2007 UTC vs.
Revision 1.33 by root, Fri Nov 9 19:33:51 2007 UTC