[ViewVC] Diff of: cvs/EV/README

Comparing EV/README (file contents):
Revision 1.20 by root, Sat Dec 22 12:05:42 2007 UTC vs.
Revision 1.27 by root, Mon May 26 05:37:18 2008 UTC

…		…
2	EV - perl interface to libev, a high performance full-featured event	2	EV - perl interface to libev, a high performance full-featured event
3	loop	3	loop
4		4
5	SYNOPSIS	5	SYNOPSIS
6	use EV;	6	use EV;
7		7
8	# TIMERS	8	# TIMERS
9		9
10	my $w = EV::timer 2, 0, sub {	10	my $w = EV::timer 2, 0, sub {
11	warn "is called after 2s";	11	warn "is called after 2s";
12	};	12	};
13		13
14	my $w = EV::timer 2, 2, sub {	14	my $w = EV::timer 2, 2, sub {
15	warn "is called roughly every 2s (repeat = 2)";	15	warn "is called roughly every 2s (repeat = 2)";
16	};	16	};
17		17
18	undef $w; # destroy event watcher again	18	undef $w; # destroy event watcher again
19		19
20	my $w = EV::periodic 0, 60, 0, sub {	20	my $w = EV::periodic 0, 60, 0, sub {
21	warn "is called every minute, on the minute, exactly";	21	warn "is called every minute, on the minute, exactly";
22	};	22	};
23
24	# IO	23
25		24	# IO
		25
26	my $w = EV::io *STDIN, EV::READ, sub {	26	my $w = EV::io *STDIN, EV::READ, sub {
27	my ($w, $revents) = @_; # all callbacks receive the watcher and event mask	27	my ($w, $revents) = @_; # all callbacks receive the watcher and event mask
28	warn "stdin is readable, you entered: ", <STDIN>;	28	warn "stdin is readable, you entered: ", <STDIN>;
29	};	29	};
30		30
31	# SIGNALS	31	# SIGNALS
32		32
33	my $w = EV::signal 'QUIT', sub {	33	my $w = EV::signal 'QUIT', sub {
34	warn "sigquit received\n";	34	warn "sigquit received\n";
35	};	35	};
36		36
37	# CHILD/PID STATUS CHANGES	37	# CHILD/PID STATUS CHANGES
38		38
39	my $w = EV::child 666, sub {	39	my $w = EV::child 666, 0, sub {
40	my ($w, $revents) = @_;	40	my ($w, $revents) = @_;
41	my $status = $w->rstatus;	41	my $status = $w->rstatus;
42	};	42	};
43		43
44	# STAT CHANGES	44	# STAT CHANGES
45	my $w = EV::stat "/etc/passwd", 10, sub {	45	my $w = EV::stat "/etc/passwd", 10, sub {
46	my ($w, $revents) = @_;	46	my ($w, $revents) = @_;
47	warn $w->path, " has changed somehow.\n";	47	warn $w->path, " has changed somehow.\n";
48	};	48	};
49		49
50	# MAINLOOP	50	# MAINLOOP
51	EV::loop; # loop until EV::unloop is called or all watchers stop	51	EV::loop; # loop until EV::unloop is called or all watchers stop
52	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
53	EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block	53	EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
54		54
55	DESCRIPTION	55	DESCRIPTION
56	This module provides an interface to libev	56	This module provides an interface to libev
57	(<http://software.schmorp.de/pkg/libev.html>). While the documentation	57	(<http://software.schmorp.de/pkg/libev.html>). While the documentation
58	below is comprehensive, one might also consult the documentation of	58	below is comprehensive, one might also consult the documentation of
59	libev itself (<http://cvs.schmorp.de/libev/ev.html>) for more subtle	59	libev itself (<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>)
60	details on watcher semantics or some discussion on the available	60	for more subtle details on watcher semantics or some discussion on the
61	backends, or how to force a specific backend with "LIBEV_FLAGS", or just	61	available backends, or how to force a specific backend with
62	about in any case because it has much more detailed information.	62	"LIBEV_FLAGS", or just about in any case because it has much more
		63	detailed information.
		64
		65	This module is very fast and scalable. It is actually so fast that you
		66	can use it through the AnyEvent module, stay portable to other event
		67	loops (if you don't rely on any watcher types not available through it)
		68	and still be faster than with any other event loop currently supported
		69	in Perl.
63		70
64	EVENT LOOPS	71	EVENT LOOPS
65	EV supports multiple event loops: There is a single "default event loop"	72	EV supports multiple event loops: There is a single "default event loop"
66	that can handle everything including signals and child watchers, and any	73	that can handle everything including signals and child watchers, and any
67	number of "dynamic event loops" that can use different backends (with	74	number of "dynamic event loops" that can use different backends (with
…		…
72	selecting a working backend (which for example rules out kqueue on most	79	selecting a working backend (which for example rules out kqueue on most
73	BSDs). Modules should, unless they have "special needs" always use the	80	BSDs). Modules should, unless they have "special needs" always use the
74	default loop as this is fastest (perl-wise), best supported by other	81	default loop as this is fastest (perl-wise), best supported by other
75	modules (e.g. AnyEvent or Coro) and most portable event loop.	82	modules (e.g. AnyEvent or Coro) and most portable event loop.
76		83
77	For specific programs you cna create additional event loops dynamically.	84	For specific programs you can create additional event loops dynamically.
78		85
79	$loop = new EV::loop [$flags]	86	$loop = new EV::loop [$flags]
80	Create a new event loop as per the specified flags. Please refer to	87	Create a new event loop as per the specified flags. Please refer to
81	the "ev_loop_new ()" function description in the libev documentation	88	the "ev_loop_new ()" function description in the libev documentation
82	(<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#GLOBAL_FUNCTI	89	(<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#GLOBAL_FUNCTI
…		…
89	loop is protected by this module.	96	loop is protected by this module.
90		97
91	$loop->loop_fork	98	$loop->loop_fork
92	Must be called after a fork in the child, before entering or	99	Must be called after a fork in the child, before entering or
93	continuing the event loop. An alternative is to use	100	continuing the event loop. An alternative is to use
94	"EV::FLAG_FORKCHECK" which calls this fucntion automatically, at	101	"EV::FLAG_FORKCHECK" which calls this function automatically, at
95	some performance loss (refer to the libev documentation).	102	some performance loss (refer to the libev documentation).
		103
		104	$loop->loop_verify
		105	Calls "ev_verify" to make internal consistency checks (for debugging
		106	libev) and abort the program if any data structures wree found to be
		107	corrupted.
		108
		109	$loop = EV::default_loop [$flags]
		110	Return the default loop (which is a singleton object). Since this
		111	module already creates the default loop with default flags,
		112	specifying flags here will not have any effect unless you destroy
		113	the default loop.
96		114
97	BASIC INTERFACE	115	BASIC INTERFACE
98	$EV::DIED	116	$EV::DIED
99	Must contain a reference to a function that is called when a	117	Must contain a reference to a function that is called when a
100	callback throws an exception (with $@ containing the error). The	118	callback throws an exception (with $@ containing the error). The
101	default prints an informative message and continues.	119	default prints an informative message and continues.
102		120
103	If this callback throws an exception it will be silently ignored.	121	If this callback throws an exception it will be silently ignored.
		122
		123	$flags = EV::supported_backends
		124	$flags = EV::recommended_backends
		125	$flags = EV::embeddable_backends
		126	Returns the set (see "EV::BACKEND_*" flags) of backends supported by
		127	this instance of EV, the set of recommended backends (supposed to be
		128	good) for this platform and the set of embeddable backends (see
		129	EMBED WATCHERS).
		130
		131	EV::sleep $seconds
		132	Block the process for the given number of (fractional) seconds.
104		133
105	$time = EV::time	134	$time = EV::time
106	Returns the current time in (fractional) seconds since the epoch.	135	Returns the current time in (fractional) seconds since the epoch.
107		136
108	$time = EV::now	137	$time = EV::now
…		…
171	descriptor $fd.	200	descriptor $fd.
172		201
173	EV::feed_signal_event ($signal)	202	EV::feed_signal_event ($signal)
174	Feed a signal event into EV. EV will react to this call as if the	203	Feed a signal event into EV. EV will react to this call as if the
175	signal specified by $signal had occured.	204	signal specified by $signal had occured.
		205
		206	EV::set_io_collect_interval $time
		207	$loop->set_io_collect_interval ($time)
		208	EV::set_timeout_collect_interval $time
		209	$loop->set_timeout_collect_interval ($time)
		210	These advanced functions set the minimum block interval when polling
		211	for I/O events and the minimum wait interval for timer events. See
		212	the libev documentation at
		213	<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONT
		214	ROLLING_THE_EVENT_LOOP> for a more detailed discussion.
176		215
177	WATCHER OBJECTS	216	WATCHER OBJECTS
178	A watcher is an object that gets created to record your interest in some	217	A watcher is an object that gets created to record your interest in some
179	event. For instance, if you want to wait for STDIN to become readable,	218	event. For instance, if you want to wait for STDIN to become readable,
180	you would create an EV::io watcher for that:	219	you would create an EV::io watcher for that:
…		…
390	changed by explicit date -s or other means such as ntpd). It is also	429	changed by explicit date -s or other means such as ntpd). It is also
391	the most complex watcher type in EV.	430	the most complex watcher type in EV.
392		431
393	It has three distinct "modes":	432	It has three distinct "modes":
394		433
395	* absolute timer ($interval = $reschedule_cb = 0)	434	* absolute timer ($interval = $reschedule_cb = 0)
		435
396	This time simply fires at the wallclock time $at and doesn't	436	This time simply fires at the wallclock time $at and doesn't
397	repeat. It will not adjust when a time jump occurs, that is, if	437	repeat. It will not adjust when a time jump occurs, that is, if
398	it is to be run at January 1st 2011 then it will run when the	438	it is to be run at January 1st 2011 then it will run when the
399	system time reaches or surpasses this time.	439	system time reaches or surpasses this time.
400		440
401	* non-repeating interval timer ($interval > 0, $reschedule_cb = 0)	441	* repeating interval timer ($interval > 0, $reschedule_cb = 0)
		442
402	In this mode the watcher will always be scheduled to time out at	443	In this mode the watcher will always be scheduled to time out at
403	the next "$at + N * $interval" time (for some integer N) and	444	the next "$at + N * $interval" time (for some integer N) and
404	then repeat, regardless of any time jumps.	445	then repeat, regardless of any time jumps.
405		446
406	This can be used to create timers that do not drift with respect	447	This can be used to create timers that do not drift with respect
…		…
415	Another way to think about it (for the mathematically inclined)	456	Another way to think about it (for the mathematically inclined)
416	is that EV::periodic will try to run the callback in this mode	457	is that EV::periodic will try to run the callback in this mode
417	at the next possible time where "$time = $at (mod $interval)",	458	at the next possible time where "$time = $at (mod $interval)",
418	regardless of any time jumps.	459	regardless of any time jumps.
419		460
420	* manual reschedule mode ($reschedule_cb = coderef)	461	* manual reschedule mode ($reschedule_cb = coderef)
		462
421	In this mode $interval and $at are both being ignored. Instead,	463	In this mode $interval and $at are both being ignored. Instead,
422	each time the periodic watcher gets scheduled, the reschedule	464	each time the periodic watcher gets scheduled, the reschedule
423	callback ($reschedule_cb) will be called with the watcher as	465	callback ($reschedule_cb) will be called with the watcher as
424	first, and the current time as second argument.	466	first, and the current time as second argument.
425		467
426	*This callback MUST NOT stop or destroy this or any other	468	*This callback MUST NOT stop or destroy this or any other
		469	periodic watcher, ever, and MUST NOT call any event loop
427	periodic watcher, ever*. If you need to stop it, return 1e30 and	470	functions or methods*. If you need to stop it, return 1e30 and
428	stop it afterwards.	471	stop it afterwards. You may create and start a "EV::prepare"
		472	watcher for this task.
429		473
430	It must return the next time to trigger, based on the passed	474	It must return the next time to trigger, based on the passed
431	time value (that is, the lowest time value larger than to the	475	time value (that is, the lowest time value larger than or equal
432	second argument). It will usually be called just before the	476	to to the second argument). It will usually be called just
433	callback will be triggered, but might be called at other times,	477	before the callback will be triggered, but might be called at
434	too.	478	other times, too.
435		479
436	This can be used to create very complex timers, such as a timer	480	This can be used to create very complex timers, such as a timer
437	that triggers on each midnight, local time (actually 24 hours	481	that triggers on each midnight, local time (actually 24 hours
438	after the last midnight, to keep the example simple. If you know	482	after the last midnight, to keep the example simple. If you know
439	a way to do it correctly in about the same space (without	483	a way to do it correctly in about the same space (without
…		…
486	$old_signum = $w->signal ($new_signal)	530	$old_signum = $w->signal ($new_signal)
487	Returns the previously set signal (always as a number not name) and	531	Returns the previously set signal (always as a number not name) and
488	optionally set a new one.	532	optionally set a new one.
489		533
490	CHILD WATCHERS - watch out for process status changes	534	CHILD WATCHERS - watch out for process status changes
491	$w = EV::child $pid, $callback	535	$w = EV::child $pid, $trace, $callback
492	$w = EV::child_ns $pid, $callback	536	$w = EV::child_ns $pid, $trace, $callback
493	$w = $loop->child ($pid, $callback)	537	$w = $loop->child ($pid, $trace, $callback)
494	$w = $loop->child_ns ($pid, $callback)	538	$w = $loop->child_ns ($pid, $trace, $callback)
495	Call the callback when a status change for pid $pid (or any pid if	539	Call the callback when a status change for pid $pid (or any pid if
496	$pid is 0) has been received. More precisely: when the process	540	$pid is 0) has been received (a status change happens when the
		541	process terminates or is killed, or, when trace is true,
		542	additionally when it is stopped or continued). More precisely: when
497	receives a "SIGCHLD", EV will fetch the outstanding exit/wait status	543	the process receives a "SIGCHLD", EV will fetch the outstanding
498	for all changed/zombie children and call the callback.	544	exit/wait status for all changed/zombie children and call the
		545	callback.
499		546
500	It is valid (and fully supported) to install a child watcher after a	547	It is valid (and fully supported) to install a child watcher after a
501	child has exited but before the event loop has started its next	548	child has exited but before the event loop has started its next
502	iteration (for example, first you "fork", then the new child process	549	iteration (for example, first you "fork", then the new child process
503	might exit, and only then do you install a child watcher in the	550	might exit, and only then do you install a child watcher in the
…		…
510	be called.	557	be called.
511		558
512	The "child_ns" variant doesn't start (activate) the newly created	559	The "child_ns" variant doesn't start (activate) the newly created
513	watcher.	560	watcher.
514		561
515	$w->set ($pid)	562	$w->set ($pid, $trace)
516	Reconfigures the watcher, see the constructor above for details. Can	563	Reconfigures the watcher, see the constructor above for details. Can
517	be called at any time.	564	be called at any time.
518		565
519	$current_pid = $w->pid	566	$current_pid = $w->pid
520	$old_pid = $w->pid ($new_pid)
521	Returns the previously set process id and optionally set a new one.	567	Returns the previously set process id and optionally set a new one.
522		568
523	$exit_status = $w->rstatus	569	$exit_status = $w->rstatus
524	Return the exit/wait status (as returned by waitpid, see the waitpid	570	Return the exit/wait status (as returned by waitpid, see the waitpid
525	entry in perlfunc).	571	entry in perlfunc).
…		…
708	process after a fork.	754	process after a fork.
709		755
710	The "fork_ns" variant doesn't start (activate) the newly created	756	The "fork_ns" variant doesn't start (activate) the newly created
711	watcher.	757	watcher.
712		758
		759	EMBED WATCHERS - when one backend isn't enough...
		760	This is a rather advanced watcher type that lets you embed one event
		761	loop into another (currently only IO events are supported in the
		762	embedded loop, other types of watchers might be handled in a delayed or
		763	incorrect fashion and must not be used).
		764
		765	See the libev documentation at
		766	<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_embed_code
		767	_when_one_backend_> for more details.
		768
		769	In short, this watcher is most useful on BSD systems without working
		770	kqueue to still be able to handle a large number of sockets:
		771
		772	my $socket_loop;
		773
		774	# check wether we use SELECT or POLL _and_ KQUEUE is supported
		775	if (
		776	(EV::backend & (EV::BACKEND_POLL \| EV::BACKEND_SELECT))
		777	&& (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE)
		778	) {
		779	# use kqueue for sockets
		780	$socket_loop = new EV::Loop EV::BACKEND_KQUEUE \| EV::FLAG_NOENV;
		781	}
		782
		783	# use the default loop otherwise
		784	$socket_loop \|\|= EV::default_loop;
		785
		786	$w = EV::embed $otherloop, $callback
		787	$w = EV::embed_ns $otherloop, $callback
		788	$w = $loop->embed ($otherloop, $callback)
		789	$w = $loop->embed_ns ($otherloop, $callback)
		790	Call the callback when the embedded event loop ($otherloop) has any
		791	I/O activity. The $callback should alwas be specified as "undef" in
		792	this version of EV, which means the embedded event loop will be
		793	managed automatically.
		794
		795	The "embed_ns" variant doesn't start (activate) the newly created
		796	watcher.
		797
		798	ASYNC WATCHERS - how to wake up another event loop
		799	Async watchers are provided by EV, but have little use in perl directly,
		800	as perl neither supports threads nor direct access to signal handlers or
		801	other contexts where they could be of value.
		802
		803	It is, however, possible to use them from the XS level.
		804
		805	Please see the libev documentation for further details.
		806
		807	$w = EV::async $callback
		808	$w = EV::async_ns $callback
		809	$w->send
		810	$bool = $w->async_pending
		811
713	PERL SIGNALS	812	PERL SIGNALS
714	While Perl signal handling (%SIG) is not affected by EV, the behaviour	813	While Perl signal handling (%SIG) is not affected by EV, the behaviour
715	with EV is as the same as any other C library: Perl-signals will only be	814	with EV is as the same as any other C library: Perl-signals will only be
716	handled when Perl runs, which means your signal handler might be invoked	815	handled when Perl runs, which means your signal handler might be invoked
717	only the next time an event callback is invoked.	816	only the next time an event callback is invoked.
…		…
751	course.	850	course.
752		851
753	SEE ALSO	852	SEE ALSO
754	EV::ADNS (asynchronous DNS), Glib::EV (makes Glib/Gtk2 use EV as event	853	EV::ADNS (asynchronous DNS), Glib::EV (makes Glib/Gtk2 use EV as event
755	loop), EV::Glib (embed Glib into EV), Coro::EV (efficient coroutines	854	loop), EV::Glib (embed Glib into EV), Coro::EV (efficient coroutines
756	with EV), Net::SNMP::EV (asynchronous SNMP).	855	with EV), Net::SNMP::EV (asynchronous SNMP), AnyEvent for event-loop
		856	agnostic and portable event driven programming.
757		857
758	AUTHOR	858	AUTHOR
759	Marc Lehmann <schmorp@schmorp.de>	859	Marc Lehmann <schmorp@schmorp.de>
760	http://home.schmorp.de/	860	http://home.schmorp.de/
761		861

Diff Legend

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

Comparing EV/README (file contents): Revision 1.20 by root, Sat Dec 22 12:05:42 2007 UTC vs. Revision 1.27 by root, Mon May 26 05:37:18 2008 UTC

Diff Legend

Comparing EV/README (file contents):
Revision 1.20 by root, Sat Dec 22 12:05:42 2007 UTC vs.
Revision 1.27 by root, Mon May 26 05:37:18 2008 UTC