[ViewVC] Diff of: cvs/AnyEvent/README

Comparing AnyEvent/README (file contents):
Revision 1.28 by root, Sat Jul 12 20:45:27 2008 UTC vs.
Revision 1.30 by root, Mon Sep 29 02:08:57 2008 UTC

…		…
5	loops	5	loops
6		6
7	SYNOPSIS	7	SYNOPSIS
8	use AnyEvent;	8	use AnyEvent;
9		9
10	my $w = AnyEvent->io (fh => $fh, poll => "r\|w", cb => sub {	10	my $w = AnyEvent->io (fh => $fh, poll => "r\|w", cb => sub { ... });
11	...
12	});
13		11
14	my $w = AnyEvent->timer (after => $seconds, cb => sub {	12	my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
		13	my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
		14
		15	print AnyEvent->now; # prints current event loop time
		16	print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
		17
		18	my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
		19
		20	my $w = AnyEvent->child (pid => $pid, cb => sub {
		21	my ($pid, $status) = @_;
15	...	22	...
16	});	23	});
17		24
18	my $w = AnyEvent->condvar; # stores whether a condition was flagged	25	my $w = AnyEvent->condvar; # stores whether a condition was flagged
19	$w->send; # wake up current and all future recv's	26	$w->send; # wake up current and all future recv's
20	$w->recv; # enters "main loop" till $condvar gets ->send	27	$w->recv; # enters "main loop" till $condvar gets ->send
		28	# use a condvar in callback mode:
		29	$w->cb (sub { $_[0]->recv });
21		30
22	INTRODUCTION/TUTORIAL	31	INTRODUCTION/TUTORIAL
23	This manpage is mainly a reference manual. If you are interested in a	32	This manpage is mainly a reference manual. If you are interested in a
24	tutorial or some gentle introduction, have a look at the AnyEvent::Intro	33	tutorial or some gentle introduction, have a look at the AnyEvent::Intro
25	manpage.	34	manpage.
…		…
321		330
322	CHILD PROCESS WATCHERS	331	CHILD PROCESS WATCHERS
323	You can also watch on a child process exit and catch its exit status.	332	You can also watch on a child process exit and catch its exit status.
324		333
325	The child process is specified by the "pid" argument (if set to 0, it	334	The child process is specified by the "pid" argument (if set to 0, it
326	watches for any child process exit). The watcher will trigger as often	335	watches for any child process exit). The watcher will triggered only
327	as status change for the child are received. This works by installing a	336	when the child process has finished and an exit status is available, not
328	signal handler for "SIGCHLD". The callback will be called with the pid	337	on any trace events (stopped/continued).
329	and exit status (as returned by waitpid), so unlike other watcher types,	338
330	you can rely on child watcher callback arguments.	339	The callback will be called with the pid and exit status (as returned by
		340	waitpid), so unlike other watcher types, you can rely on child watcher
		341	callback arguments.
		342
		343	This watcher type works by installing a signal handler for "SIGCHLD",
		344	and since it cannot be shared, nothing else should use SIGCHLD or reap
		345	random child processes (waiting for specific child processes, e.g.
		346	inside "system", is just fine).
331		347
332	There is a slight catch to child watchers, however: you usually start	348	There is a slight catch to child watchers, however: you usually start
333	them after the child process was created, and this means the process	349	them after the child process was created, and this means the process
334	could have exited already (and no SIGCHLD will be sent anymore).	350	could have exited already (and no SIGCHLD will be sent anymore).
335		351
…		…
371	The instrument to do that is called a "condition variable", so called	387	The instrument to do that is called a "condition variable", so called
372	because they represent a condition that must become true.	388	because they represent a condition that must become true.
373		389
374	Condition variables can be created by calling the "AnyEvent->condvar"	390	Condition variables can be created by calling the "AnyEvent->condvar"
375	method, usually without arguments. The only argument pair allowed is	391	method, usually without arguments. The only argument pair allowed is
		392
376	"cb", which specifies a callback to be called when the condition	393	"cb", which specifies a callback to be called when the condition
377	variable becomes true.	394	variable becomes true, with the condition variable as the first argument
		395	(but not the results).
378		396
379	After creation, the condition variable is "false" until it becomes	397	After creation, the condition variable is "false" until it becomes
380	"true" by calling the "send" method (or calling the condition variable	398	"true" by calling the "send" method (or calling the condition variable
381	as if it were a callback, read about the caveats in the description for	399	as if it were a callback, read about the caveats in the description for
382	the "->send" method).	400	the "->send" method).
…		…
438		456
439	my $done = AnyEvent->condvar;	457	my $done = AnyEvent->condvar;
440	my $delay = AnyEvent->timer (after => 5, cb => $done);	458	my $delay = AnyEvent->timer (after => 5, cb => $done);
441	$done->recv;	459	$done->recv;
442		460
		461	Example: Imagine an API that returns a condvar and doesn't support
		462	callbacks. This is how you make a synchronous call, for example from the
		463	main program:
		464
		465	use AnyEvent::CouchDB;
		466
		467	...
		468
		469	my @info = $couchdb->info->recv;
		470
		471	And this is how you would just ste a callback to be called whenever the
		472	results are available:
		473
		474	$couchdb->info->cb (sub {
		475	my @info = $_[0]->recv;
		476	});
		477
443	METHODS FOR PRODUCERS	478	METHODS FOR PRODUCERS
444	These methods should only be used by the producing side, i.e. the	479	These methods should only be used by the producing side, i.e. the
445	code/module that eventually sends the signal. Note that it is also the	480	code/module that eventually sends the signal. Note that it is also the
446	producer side which creates the condvar in most cases, but it isn't	481	producer side which creates the condvar in most cases, but it isn't
447	uncommon for the consumer to create it as well.	482	uncommon for the consumer to create it as well.
…		…
567		602
568	$bool = $cv->ready	603	$bool = $cv->ready
569	Returns true when the condition is "true", i.e. whether "send" or	604	Returns true when the condition is "true", i.e. whether "send" or
570	"croak" have been called.	605	"croak" have been called.
571		606
572	$cb = $cv->cb ([new callback])	607	$cb = $cv->cb ($cb->($cv))
573	This is a mutator function that returns the callback set and	608	This is a mutator function that returns the callback set and
574	optionally replaces it before doing so.	609	optionally replaces it before doing so.
575		610
576	The callback will be called when the condition becomes "true", i.e.	611	The callback will be called when the condition becomes "true", i.e.
577	when "send" or "croak" are called, with the only argument being the	612	when "send" or "croak" are called, with the only argument being the
…		…
762		797
763	IO::Lambda	798	IO::Lambda
764	The lambda approach to I/O - don't ask, look there. Can use	799	The lambda approach to I/O - don't ask, look there. Can use
765	AnyEvent.	800	AnyEvent.
766		801
767	SUPPLYING YOUR OWN EVENT MODEL INTERFACE	802	ERROR AND EXCEPTION HANDLING
768	This is an advanced topic that you do not normally need to use AnyEvent	803	In general, AnyEvent does not do any error handling - it relies on the
769	in a module. This section is only of use to event loop authors who want	804	caller to do that if required. The AnyEvent::Strict module (see also the
770	to provide AnyEvent compatibility.	805	"PERL_ANYEVENT_STRICT" environment variable, below) provides strict
		806	checking of all AnyEvent methods, however, which is highly useful during
		807	development.
771		808
772	If you need to support another event library which isn't directly	809	As for exception handling (i.e. runtime errors and exceptions thrown
773	supported by AnyEvent, you can supply your own interface to it by	810	while executing a callback), this is not only highly event-loop
774	pushing, before the first watcher gets created, the package name of the	811	specific, but also not in any way wrapped by this module, as this is the
775	event module and the package name of the interface to use onto	812	job of the main program.
776	@AnyEvent::REGISTRY. You can do that before and even without loading
777	AnyEvent, so it is reasonably cheap.
778		813
779	Example:	814	The pure perl event loop simply re-throws the exception (usually within
780		815	"condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
781	push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];	816	Glib uses "install_exception_handler" and so on.
782
783	This tells AnyEvent to (literally) use the "urxvt::anyevent::"
784	package/class when it finds the "urxvt" package/module is already
785	loaded.
786
787	When AnyEvent is loaded and asked to find a suitable event model, it
788	will first check for the presence of urxvt by trying to "use" the
789	"urxvt::anyevent" module.
790
791	The class should provide implementations for all watcher types. See
792	AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
793	so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
794	the sources.
795
796	If you don't provide "signal" and "child" watchers than AnyEvent will
797	provide suitable (hopefully) replacements.
798
799	The above example isn't fictitious, the rxvt-unicode (a.k.a. urxvt)
800	terminal emulator uses the above line as-is. An interface isn't included
801	in AnyEvent because it doesn't make sense outside the embedded
802	interpreter inside rxvt-unicode, and it is updated and maintained as
803	part of the rxvt-unicode distribution.
804
805	rxvt-unicode also cheats a bit by not providing blocking access to
806	condition variables: code blocking while waiting for a condition will
807	"die". This still works with most modules/usages, and blocking calls
808	must not be done in an interactive application, so it makes sense.
809		817
810	ENVIRONMENT VARIABLES	818	ENVIRONMENT VARIABLES
811	The following environment variables are used by this module:	819	The following environment variables are used by this module or its
		820	submodules:
812		821
813	"PERL_ANYEVENT_VERBOSE"	822	"PERL_ANYEVENT_VERBOSE"
814	By default, AnyEvent will be completely silent except in fatal	823	By default, AnyEvent will be completely silent except in fatal
815	conditions. You can set this environment variable to make AnyEvent	824	conditions. You can set this environment variable to make AnyEvent
816	more talkative.	825	more talkative.
…		…
829	thoroughly check the arguments passed to most method calls. If it	838	thoroughly check the arguments passed to most method calls. If it
830	finds any problems it will croak.	839	finds any problems it will croak.
831		840
832	In other words, enables "strict" mode.	841	In other words, enables "strict" mode.
833		842
834	Unlike "use strict" it is definitely recommended ot keep it off in	843	Unlike "use strict", it is definitely recommended ot keep it off in
835	production.	844	production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment
		845	while developing programs can be very useful, however.
836		846
837	"PERL_ANYEVENT_MODEL"	847	"PERL_ANYEVENT_MODEL"
838	This can be used to specify the event model to be used by AnyEvent,	848	This can be used to specify the event model to be used by AnyEvent,
839	before auto detection and -probing kicks in. It must be a string	849	before auto detection and -probing kicks in. It must be a string
840	consisting entirely of ASCII letters. The string "AnyEvent::Impl::"	850	consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
…		…
881	EDNS0 in its DNS requests.	891	EDNS0 in its DNS requests.
882		892
883	"PERL_ANYEVENT_MAX_FORKS"	893	"PERL_ANYEVENT_MAX_FORKS"
884	The maximum number of child processes that	894	The maximum number of child processes that
885	"AnyEvent::Util::fork_call" will create in parallel.	895	"AnyEvent::Util::fork_call" will create in parallel.
		896
		897	SUPPLYING YOUR OWN EVENT MODEL INTERFACE
		898	This is an advanced topic that you do not normally need to use AnyEvent
		899	in a module. This section is only of use to event loop authors who want
		900	to provide AnyEvent compatibility.
		901
		902	If you need to support another event library which isn't directly
		903	supported by AnyEvent, you can supply your own interface to it by
		904	pushing, before the first watcher gets created, the package name of the
		905	event module and the package name of the interface to use onto
		906	@AnyEvent::REGISTRY. You can do that before and even without loading
		907	AnyEvent, so it is reasonably cheap.
		908
		909	Example:
		910
		911	push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
		912
		913	This tells AnyEvent to (literally) use the "urxvt::anyevent::"
		914	package/class when it finds the "urxvt" package/module is already
		915	loaded.
		916
		917	When AnyEvent is loaded and asked to find a suitable event model, it
		918	will first check for the presence of urxvt by trying to "use" the
		919	"urxvt::anyevent" module.
		920
		921	The class should provide implementations for all watcher types. See
		922	AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
		923	so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
		924	the sources.
		925
		926	If you don't provide "signal" and "child" watchers than AnyEvent will
		927	provide suitable (hopefully) replacements.
		928
		929	The above example isn't fictitious, the rxvt-unicode (a.k.a. urxvt)
		930	terminal emulator uses the above line as-is. An interface isn't included
		931	in AnyEvent because it doesn't make sense outside the embedded
		932	interpreter inside rxvt-unicode, and it is updated and maintained as
		933	part of the rxvt-unicode distribution.
		934
		935	rxvt-unicode also cheats a bit by not providing blocking access to
		936	condition variables: code blocking while waiting for a condition will
		937	"die". This still works with most modules/usages, and blocking calls
		938	must not be done in an interactive application, so it makes sense.
886		939
887	EXAMPLE PROGRAM	940	EXAMPLE PROGRAM
888	The following program uses an I/O watcher to read data from STDIN, a	941	The following program uses an I/O watcher to read data from STDIN, a
889	timer to display a message once per second, and a condition variable to	942	timer to display a message once per second, and a condition variable to
890	quit the program when the user enters quit:	943	quit the program when the user enters quit:

Diff Legend

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

Comparing AnyEvent/README (file contents): Revision 1.28 by root, Sat Jul 12 20:45:27 2008 UTC vs. Revision 1.30 by root, Mon Sep 29 02:08:57 2008 UTC

Diff Legend

Comparing AnyEvent/README (file contents):
Revision 1.28 by root, Sat Jul 12 20:45:27 2008 UTC vs.
Revision 1.30 by root, Mon Sep 29 02:08:57 2008 UTC