[ViewVC] Diff of: cvs/Coro/README

Comparing Coro/README (file contents):
Revision 1.8 by root, Thu Apr 19 10:37:26 2007 UTC vs.
Revision 1.20 by root, Tue Nov 25 20:48:41 2008 UTC

…		…
1	NAME	1	NAME
2	Coro - coroutine process abstraction	2	Coro - the only real threads in perl
3		3
4	SYNOPSIS	4	SYNOPSIS
5	use Coro;	5	use Coro;
6		6
7	async {	7	async {
8	# some asynchronous thread of execution	8	# some asynchronous thread of execution
		9	print "2\n";
		10	cede; # yield back to main
		11	print "4\n";
9	};	12	};
10		13	print "1\n";
11	# alternatively create an async coroutine like this:	14	cede; # yield to coroutine
12		15	print "3\n";
13	sub some_func : Coro {	16	cede; # and again
14	# some more async code
15	}	17
16		18	# use locking
17	cede;	19	use Coro::Semaphore;
		20	my $lock = new Coro::Semaphore;
		21	my $locked;
		22
		23	$lock->down;
		24	$locked = 1;
		25	$lock->up;
18		26
19	DESCRIPTION	27	DESCRIPTION
20	This module collection manages coroutines. Coroutines are similar to	28	For a tutorial-style introduction, please read the Coro::Intro manpage.
		29	This manpage mainly contains reference information.
		30
		31	This module collection manages continuations in general, most often in
		32	the form of cooperative threads (also called coroutines in the
		33	documentation). They are similar to kernel threads but don't (in
21	threads but don't run in parallel at the same time even on SMP machines.	34	general) run in parallel at the same time even on SMP machines. The
22	The specific flavor of coroutine used in this module also guarantees you	35	specific flavor of thread offered by this module also guarantees you
23	that it will not switch between coroutines unless necessary, at	36	that it will not switch between threads unless necessary, at
24	easily-identified points in your program, so locking and parallel access	37	easily-identified points in your program, so locking and parallel access
25	are rarely an issue, making coroutine programming much safer than	38	are rarely an issue, making thread programming much safer and easier
26	threads programming.	39	than using other thread models.
27		40
28	(Perl, however, does not natively support real threads but instead does	41	Unlike the so-called "Perl threads" (which are not actually real threads
29	a very slow and memory-intensive emulation of processes using threads.	42	but only the windows process emulation ported to unix), Coro provides a
30	This is a performance win on Windows machines, and a loss everywhere	43	full shared address space, which makes communication between threads
31	else).	44	very easy. And threads are fast, too: disabling the Windows process
		45	emulation code in your perl and using Coro can easily result in a two to
		46	four times speed increase for your programs.
32		47
		48	Coro achieves that by supporting multiple running interpreters that
		49	share data, which is especially useful to code pseudo-parallel processes
		50	and for event-based programming, such as multiple HTTP-GET requests
		51	running concurrently. See Coro::AnyEvent to learn more on how to
		52	integrate Coro into an event-based environment.
		53
33	In this module, coroutines are defined as "callchain + lexical variables	54	In this module, a thread is defined as "callchain + lexical variables +
34	+ @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own	55	@_ + $_ + $@ + $/ + C stack), that is, a thread has its own callchain,
35	callchain, its own set of lexicals and its own set of perls most	56	its own set of lexicals and its own set of perls most important global
36	important global variables.	57	variables (see Coro::State for more configuration and background info).
37		58
		59	See also the "SEE ALSO" section at the end of this document - the Coro
		60	module family is quite large.
		61
		62	GLOBAL VARIABLES
38	$main	63	$Coro::main
39	This coroutine represents the main program.	64	This variable stores the coroutine object that represents the main
		65	program. While you cna "ready" it and do most other things you can
		66	do to coroutines, it is mainly useful to compare again
		67	$Coro::current, to see whether you are running in the main program
		68	or not.
40		69
41	$current (or as function: current)	70	$Coro::current
42	The current coroutine (the last coroutine switched to). The initial	71	The coroutine object representing the current coroutine (the last
		72	coroutine that the Coro scheduler switched to). The initial value is
43	value is $main (of course).	73	$Coro::main (of course).
44		74
45	This variable is strictly read-only. It is provided for	75	This variable is strictly read-only. You can take copies of the
46	performance reasons. If performance is not essential you are	76	value stored in it and use it as any other coroutine object, but you
47	encouraged to use the "Coro::current" function instead.	77	must not otherwise modify the variable itself.
48		78
49	$idle	79	$Coro::idle
		80	This variable is mainly useful to integrate Coro into event loops.
		81	It is usually better to rely on Coro::AnyEvent or Coro::EV, as this
		82	is pretty low-level functionality.
		83
		84	This variable stores either a coroutine or a callback.
		85
50	A callback that is called whenever the scheduler finds no ready	86	If it is a callback, the it is called whenever the scheduler finds
51	coroutines to run. The default implementation prints "FATAL:	87	no ready coroutines to run. The default implementation prints
52	deadlock detected" and exits, because the program has no other way	88	"FATAL: deadlock detected" and exits, because the program has no
53	to continue.	89	other way to continue.
54		90
		91	If it is a coroutine object, then this object will be readied
		92	(without invoking any ready hooks, however) when the scheduler finds
		93	no other ready coroutines to run.
		94
55	This hook is overwritten by modules such as "Coro::Timer" and	95	This hook is overwritten by modules such as "Coro::EV" and
56	"Coro::Event" to wait on an external event that hopefully wake up a	96	"Coro::AnyEvent" to wait on an external event that hopefully wake up
57	coroutine so the scheduler can run it.	97	a coroutine so the scheduler can run it.
		98
		99	Note that the callback must not, under any circumstances, block
		100	the current coroutine. Normally, this is achieved by having an "idle
		101	coroutine" that calls the event loop and then blocks again, and then
		102	readying that coroutine in the idle handler, or by simply placing
		103	the idle coroutine in this variable.
		104
		105	See Coro::Event or Coro::AnyEvent for examples of using this
		106	technique.
58		107
59	Please note that if your callback recursively invokes perl (e.g. for	108	Please note that if your callback recursively invokes perl (e.g. for
60	event handlers), then it must be prepared to be called recursively.	109	event handlers), then it must be prepared to be called recursively
		110	itself.
61		111
62	STATIC METHODS	112	SIMPLE COROUTINE CREATION
63	Static methods are actually functions that operate on the current
64	coroutine only.
65
66	async { ... } [@args...]	113	async { ... } [@args...]
67	Create a new asynchronous coroutine and return it's coroutine object	114	Create a new coroutine and return its coroutine object (usually
68	(usually unused). When the sub returns the new coroutine is	115	unused). The coroutine will be put into the ready queue, so it will
		116	start running automatically on the next scheduler run.
		117
		118	The first argument is a codeblock/closure that should be executed in
		119	the coroutine. When it returns argument returns the coroutine is
69	automatically terminated.	120	automatically terminated.
		121
		122	The remaining arguments are passed as arguments to the closure.
		123
		124	See the "Coro::State::new" constructor for info about the coroutine
		125	environment in which coroutines are executed.
70		126
71	Calling "exit" in a coroutine will do the same as calling exit	127	Calling "exit" in a coroutine will do the same as calling exit
72	outside the coroutine. Likewise, when the coroutine dies, the	128	outside the coroutine. Likewise, when the coroutine dies, the
73	program will exit, just as it would in the main program.	129	program will exit, just as it would in the main program.
74		130
		131	If you do not want that, you can provide a default "die" handler, or
		132	simply avoid dieing (by use of "eval").
		133
75	# create a new coroutine that just prints its arguments	134	Example: Create a new coroutine that just prints its arguments.
		135
76	async {	136	async {
77	print "@_\n";	137	print "@_\n";
78	} 1,2,3,4;	138	} 1,2,3,4;
79		139
80	async_pool { ... } [@args...]	140	async_pool { ... } [@args...]
81	Similar to "async", but uses a coroutine pool, so you should not	141	Similar to "async", but uses a coroutine pool, so you should not
82	call terminate or join (although you are allowed to), and you get a	142	call terminate or join on it (although you are allowed to), and you
83	coroutine that might have executed other code already (which can be	143	get a coroutine that might have executed other code already (which
84	good or bad :).	144	can be good or bad :).
85		145
		146	On the plus side, this function is about twice as fast as creating
		147	(and destroying) a completely new coroutine, so if you need a lot of
		148	generic coroutines in quick successsion, use "async_pool", not
		149	"async".
		150
86	Also, the block is executed in an "eval" context and a warning will	151	The code block is executed in an "eval" context and a warning will
87	be issued in case of an exception instead of terminating the	152	be issued in case of an exception instead of terminating the
88	program, as "async" does. As the coroutine is being reused, stuff	153	program, as "async" does. As the coroutine is being reused, stuff
89	like "on_destroy" will not work in the expected way, unless you call	154	like "on_destroy" will not work in the expected way, unless you call
90	terminate or cancel, which somehow defeats the purpose of pooling.	155	terminate or cancel, which somehow defeats the purpose of pooling
		156	(but is fine in the exceptional case).
91		157
92	The priority will be reset to 0 after each job, otherwise the	158	The priority will be reset to 0 after each run, tracing will be
93	coroutine will be re-used "as-is".	159	disabled, the description will be reset and the default output
		160	filehandle gets restored, so you can change all these. Otherwise the
		161	coroutine will be re-used "as-is": most notably if you change other
		162	per-coroutine global stuff such as $/ you must needs revert that
		163	change, which is most simply done by using local as in: "local $/".
94		164
95	The pool size is limited to 8 idle coroutines (this can be adjusted	165	The idle pool size is limited to 8 idle coroutines (this can be
96	by changing $Coro::POOL_SIZE), and there can be as many non-idle	166	adjusted by changing $Coro::POOL_SIZE), but there can be as many
97	coros as required.	167	non-idle coros as required.
98		168
99	If you are concerned about pooled coroutines growing a lot because a	169	If you are concerned about pooled coroutines growing a lot because a
100	single "async_pool" used a lot of stackspace you can e.g.	170	single "async_pool" used a lot of stackspace you can e.g.
101	"async_pool { terminate }" once per second or so to slowly replenish	171	"async_pool { terminate }" once per second or so to slowly replenish
102	the pool.	172	the pool. In addition to that, when the stacks used by a handler
		173	grows larger than 32kb (adjustable via $Coro::POOL_RSS) it will also
		174	be destroyed.
		175
		176	STATIC METHODS
		177	Static methods are actually functions that implicitly operate on the
		178	current coroutine.
103		179
104	schedule	180	schedule
105	Calls the scheduler. Please note that the current coroutine will not	181	Calls the scheduler. The scheduler will find the next coroutine that
		182	is to be run from the ready queue and switches to it. The next
		183	coroutine to be run is simply the one with the highest priority that
		184	is longest in its ready queue. If there is no coroutine ready, it
		185	will clal the $Coro::idle hook.
		186
		187	Please note that the current coroutine will not be put into the
106	be put into the ready queue, so calling this function usually means	188	ready queue, so calling this function usually means you will never
107	you will never be called again unless something else (e.g. an event	189	be called again unless something else (e.g. an event handler) calls
108	handler) calls ready.	190	"->ready", thus waking you up.
109		191
110	The canonical way to wait on external events is this:	192	This makes "schedule" the generic method to use to block the
		193	current coroutine and wait for events: first you remember the
		194	current coroutine in a variable, then arrange for some callback of
		195	yours to call "->ready" on that once some event happens, and last
		196	you call "schedule" to put yourself to sleep. Note that a lot of
		197	things can wake your coroutine up, so you need to check whether the
		198	event indeed happened, e.g. by storing the status in a variable.
111		199
112	{	200	See HOW TO WAIT FOR A CALLBACK, below, for some ways to wait for
113	# remember current coroutine	201	callbacks.
114	my $current = $Coro::current;
115
116	# register a hypothetical event handler
117	on_event_invoke sub {
118	# wake up sleeping coroutine
119	$current->ready;
120	undef $current;
121	};
122
123	# call schedule until event occurred.
124	# in case we are woken up for other reasons
125	# (current still defined), loop.
126	Coro::schedule while $current;
127	}
128		202
129	cede	203	cede
130	"Cede" to other coroutines. This function puts the current coroutine	204	"Cede" to other coroutines. This function puts the current coroutine
131	into the ready queue and calls "schedule", which has the effect of	205	into the ready queue and calls "schedule", which has the effect of
132	giving up the current "timeslice" to other coroutines of the same or	206	giving up the current "timeslice" to other coroutines of the same or
133	higher priority.	207	higher priority. Once your coroutine gets its turn again it will
		208	automatically be resumed.
134		209
135	Returns true if at least one coroutine switch has happened.	210	This function is often called "yield" in other languages.
136		211
137	Coro::cede_notself	212	Coro::cede_notself
138	Works like cede, but is not exported by default and will cede to any	213	Works like cede, but is not exported by default and will cede to
139	coroutine, regardless of priority, once.	214	any coroutine, regardless of priority. This is useful sometimes to
140		215	ensure progress is made.
141	Returns true if at least one coroutine switch has happened.
142		216
143	terminate [arg...]	217	terminate [arg...]
144	Terminates the current coroutine with the given status values (see	218	Terminates the current coroutine with the given status values (see
145	cancel).	219	cancel).
146		220
147	# dynamic methods	221	killall
		222	Kills/terminates/cancels all coroutines except the currently running
		223	one. This is useful after a fork, either in the child or the parent,
		224	as usually only one of them should inherit the running coroutines.
148		225
		226	Note that while this will try to free some of the main programs
		227	resources, you cannot free all of them, so if a coroutine that is
		228	not the main program calls this function, there will be some
		229	one-time resource leak.
		230
149	COROUTINE METHODS	231	COROUTINE OBJECT METHODS
150	These are the methods you can call on coroutine objects.	232	These are the methods you can call on coroutine objects (or to create
		233	them).
151		234
152	new Coro \&sub [, @args...]	235	new Coro \&sub [, @args...]
153	Create a new coroutine and return it. When the sub returns the	236	Create a new coroutine and return it. When the sub returns, the
154	coroutine automatically terminates as if "terminate" with the	237	coroutine automatically terminates as if "terminate" with the
155	returned values were called. To make the coroutine run you must	238	returned values were called. To make the coroutine run you must
156	first put it into the ready queue by calling the ready method.	239	first put it into the ready queue by calling the ready method.
157		240
158	See "async" for additional discussion.	241	See "async" and "Coro::State::new" for additional info about the
		242	coroutine environment.
159		243
160	$success = $coroutine->ready	244	$success = $coroutine->ready
161	Put the given coroutine into the ready queue (according to it's	245	Put the given coroutine into the end of its ready queue (there is
162	priority) and return true. If the coroutine is already in the ready	246	one queue for each priority) and return true. If the coroutine is
163	queue, do nothing and return false.	247	already in the ready queue, do nothing and return false.
		248
		249	This ensures that the scheduler will resume this coroutine
		250	automatically once all the coroutines of higher priority and all
		251	coroutines of the same priority that were put into the ready queue
		252	earlier have been resumed.
164		253
165	$is_ready = $coroutine->is_ready	254	$is_ready = $coroutine->is_ready
166	Return wether the coroutine is currently the ready queue or not,	255	Return whether the coroutine is currently the ready queue or not,
167		256
168	$coroutine->cancel (arg...)	257	$coroutine->cancel (arg...)
169	Terminates the given coroutine and makes it return the given	258	Terminates the given coroutine and makes it return the given
170	arguments as status (default: the empty list). Never returns if the	259	arguments as status (default: the empty list). Never returns if the
171	coroutine is the current coroutine.	260	coroutine is the current coroutine.
172		261
		262	$coroutine->schedule_to
		263	Puts the current coroutine to sleep (like "Coro::schedule"), but
		264	instead of continuing with the next coro from the ready queue,
		265	always switch to the given coroutine object (regardless of priority
		266	etc.). The readyness state of that coroutine isn't changed.
		267
		268	This is an advanced method for special cases - I'd love to hear
		269	about any uses for this one.
		270
		271	$coroutine->cede_to
		272	Like "schedule_to", but puts the current coroutine into the ready
		273	queue. This has the effect of temporarily switching to the given
		274	coroutine, and continuing some time later.
		275
		276	This is an advanced method for special cases - I'd love to hear
		277	about any uses for this one.
		278
		279	$coroutine->throw ([$scalar])
		280	If $throw is specified and defined, it will be thrown as an
		281	exception inside the coroutine at the next convenient point in time.
		282	Otherwise clears the exception object.
		283
		284	Coro will check for the exception each time a schedule-like-function
		285	returns, i.e. after each "schedule", "cede",
		286	"Coro::Semaphore->down", "Coro::Handle->readable" and so on. Most of
		287	these functions detect this case and return early in case an
		288	exception is pending.
		289
		290	The exception object will be thrown "as is" with the specified
		291	scalar in $@, i.e. if it is a string, no line number or newline will
		292	be appended (unlike with "die").
		293
		294	This can be used as a softer means than "cancel" to ask a coroutine
		295	to end itself, although there is no guarantee that the exception
		296	will lead to termination, and if the exception isn't caught it might
		297	well end the whole program.
		298
		299	You might also think of "throw" as being the moral equivalent of
		300	"kill"ing a coroutine with a signal (in this case, a scalar).
		301
173	$coroutine->join	302	$coroutine->join
174	Wait until the coroutine terminates and return any values given to	303	Wait until the coroutine terminates and return any values given to
175	the "terminate" or "cancel" functions. "join" can be called multiple	304	the "terminate" or "cancel" functions. "join" can be called
176	times from multiple coroutine.	305	concurrently from multiple coroutines, and all will be resumed and
		306	given the status return once the $coroutine terminates.
177		307
178	$coroutine->on_destroy (\&cb)	308	$coroutine->on_destroy (\&cb)
179	Registers a callback that is called when this coroutine gets	309	Registers a callback that is called when this coroutine gets
180	destroyed, but before it is joined. The callback gets passed the	310	destroyed, but before it is joined. The callback gets passed the
181	terminate arguments, if any.	311	terminate arguments, if any, and must not die, under any
		312	circumstances.
182		313
183	$oldprio = $coroutine->prio ($newprio)	314	$oldprio = $coroutine->prio ($newprio)
184	Sets (or gets, if the argument is missing) the priority of the	315	Sets (or gets, if the argument is missing) the priority of the
185	coroutine. Higher priority coroutines get run before lower priority	316	coroutine. Higher priority coroutines get run before lower priority
186	coroutines. Priorities are small signed integers (currently -4 ..	317	coroutines. Priorities are small signed integers (currently -4 ..
209	$olddesc = $coroutine->desc ($newdesc)	340	$olddesc = $coroutine->desc ($newdesc)
210	Sets (or gets in case the argument is missing) the description for	341	Sets (or gets in case the argument is missing) the description for
211	this coroutine. This is just a free-form string you can associate	342	this coroutine. This is just a free-form string you can associate
212	with a coroutine.	343	with a coroutine.
213		344
		345	This method simply sets the "$coroutine->{desc}" member to the given
		346	string. You can modify this member directly if you wish.
		347
214	GLOBAL FUNCTIONS	348	GLOBAL FUNCTIONS
215	Coro::nready	349	Coro::nready
216	Returns the number of coroutines that are currently in the ready	350	Returns the number of coroutines that are currently in the ready
217	state, i.e. that can be switched to. The value 0 means that the only	351	state, i.e. that can be switched to by calling "schedule" directory
218	runnable coroutine is the currently running one, so "cede" would	352	or indirectly. The value 0 means that the only runnable coroutine is
219	have no effect, and "schedule" would cause a deadlock unless there	353	the currently running one, so "cede" would have no effect, and
		354	"schedule" would cause a deadlock unless there is an idle handler
220	is an idle handler that wakes up some coroutines.	355	that wakes up some coroutines.
221		356
222	my $guard = Coro::guard { ... }	357	my $guard = Coro::guard { ... }
223	This creates and returns a guard object. Nothing happens until the	358	This creates and returns a guard object. Nothing happens until the
224	object gets destroyed, in which case the codeblock given as argument	359	object gets destroyed, in which case the codeblock given as argument
225	will be executed. This is useful to free locks or other resources in	360	will be executed. This is useful to free locks or other resources in
…		…
238	# do something that requires $busy to be true	373	# do something that requires $busy to be true
239	}	374	}
240		375
241	unblock_sub { ... }	376	unblock_sub { ... }
242	This utility function takes a BLOCK or code reference and "unblocks"	377	This utility function takes a BLOCK or code reference and "unblocks"
243	it, returning the new coderef. This means that the new coderef will	378	it, returning a new coderef. Unblocking means that calling the new
244	return immediately without blocking, returning nothing, while the	379	coderef will return immediately without blocking, returning nothing,
245	original code ref will be called (with parameters) from within its	380	while the original code ref will be called (with parameters) from
246	own coroutine.	381	within another coroutine.
247		382
248	The reason this function exists is that many event libraries (such	383	The reason this function exists is that many event libraries (such
249	as the venerable Event module) are not coroutine-safe (a weaker form	384	as the venerable Event module) are not coroutine-safe (a weaker form
250	of thread-safety). This means you must not block within event	385	of reentrancy). This means you must not block within event
251	callbacks, otherwise you might suffer from crashes or worse.	386	callbacks, otherwise you might suffer from crashes or worse. The
		387	only event library currently known that is safe to use without
		388	"unblock_sub" is EV.
252		389
253	This function allows your callbacks to block by executing them in	390	This function allows your callbacks to block by executing them in
254	another coroutine where it is safe to block. One example where	391	another coroutine where it is safe to block. One example where
255	blocking is handy is when you use the Coro::AIO functions to save	392	blocking is handy is when you use the Coro::AIO functions to save
256	results to disk.	393	results to disk, for example.
257		394
258	In short: simply use "unblock_sub { ... }" instead of "sub { ... }"	395	In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
259	when creating event callbacks that want to block.	396	when creating event callbacks that want to block.
260		397
		398	If your handler does not plan to block (e.g. simply sends a message
		399	to another coroutine, or puts some other coroutine into the ready
		400	queue), there is no reason to use "unblock_sub".
		401
		402	Note that you also need to use "unblock_sub" for any other callbacks
		403	that are indirectly executed by any C-based event loop. For example,
		404	when you use a module that uses AnyEvent (and you use
		405	Coro::AnyEvent) and it provides callbacks that are the result of
		406	some event callback, then you must not block either, or use
		407	"unblock_sub".
		408
		409	$cb = Coro::rouse_cb
		410	Create and return a "rouse callback". That's a code reference that,
		411	when called, will remember a copy of its arguments and notify the
		412	owner coroutine of the callback.
		413
		414	See the next function.
		415
		416	@args = Coro::rouse_wait [$cb]
		417	Wait for the specified rouse callback (or the last one that was
		418	created in this coroutine).
		419
		420	As soon as the callback is invoked (or when the callback was invoked
		421	before "rouse_wait"), it will return the arguments originally passed
		422	to the rouse callback.
		423
		424	See the section HOW TO WAIT FOR A CALLBACK for an actual usage
		425	example.
		426
		427	HOW TO WAIT FOR A CALLBACK
		428	It is very common for a coroutine to wait for some callback to be
		429	called. This occurs naturally when you use coroutines in an otherwise
		430	event-based program, or when you use event-based libraries.
		431
		432	These typically register a callback for some event, and call that
		433	callback when the event occured. In a coroutine, however, you typically
		434	want to just wait for the event, simplyifying things.
		435
		436	For example "AnyEvent->child" registers a callback to be called when a
		437	specific child has exited:
		438
		439	my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... });
		440
		441	But from withina coroutine, you often just want to write this:
		442
		443	my $status = wait_for_child $pid;
		444
		445	Coro offers two functions specifically designed to make this easy,
		446	"Coro::rouse_cb" and "Coro::rouse_wait".
		447
		448	The first function, "rouse_cb", generates and returns a callback that,
		449	when invoked, will save its arguments and notify the coroutine that
		450	created the callback.
		451
		452	The second function, "rouse_wait", waits for the callback to be called
		453	(by calling "schedule" to go to sleep) and returns the arguments
		454	originally passed to the callback.
		455
		456	Using these functions, it becomes easy to write the "wait_for_child"
		457	function mentioned above:
		458
		459	sub wait_for_child($) {
		460	my ($pid) = @_;
		461
		462	my $watcher = AnyEvent->child (pid => $pid, cb => Coro::rouse_cb);
		463
		464	my ($rpid, $rstatus) = Coro::rouse_wait;
		465	$rstatus
		466	}
		467
		468	In the case where "rouse_cb" and "rouse_wait" are not flexible enough,
		469	you can roll your own, using "schedule":
		470
		471	sub wait_for_child($) {
		472	my ($pid) = @_;
		473
		474	# store the current coroutine in $current,
		475	# and provide result variables for the closure passed to ->child
		476	my $current = $Coro::current;
		477	my ($done, $rstatus);
		478
		479	# pass a closure to ->child
		480	my $watcher = AnyEvent->child (pid => $pid, cb => sub {
		481	$rstatus = $_[1]; # remember rstatus
		482	$done = 1; # mark $rstatus as valud
		483	});
		484
		485	# wait until the closure has been called
		486	schedule while !$done;
		487
		488	$rstatus
		489	}
		490
261	BUGS/LIMITATIONS	491	BUGS/LIMITATIONS
262	- you must make very sure that no coro is still active on global	492	fork with pthread backend
263	destruction. very bad things might happen otherwise (usually segfaults).	493	When Coro is compiled using the pthread backend (which isn't
		494	recommended but required on many BSDs as their libcs are completely
		495	broken), then coroutines will not survive a fork. There is no known
		496	workaround except to fix your libc and use a saner backend.
264		497
		498	perl process emulation ("threads")
265	- this module is not thread-safe. You should only ever use this module	499	This module is not perl-pseudo-thread-safe. You should only ever use
266	from the same thread (this requirement might be loosened in the future	500	this module from the first thread (this requirement might be removed
267	to allow per-thread schedulers, but Coro::State does not yet allow	501	in the future to allow per-thread schedulers, but Coro::State does
268	this).	502	not yet allow this). I recommend disabling thread support and using
		503	processes, as having the windows process emulation enabled under
		504	unix roughly halves perl performance, even when not used.
		505
		506	coroutine switching not signal safe
		507	You must not switch to another coroutine from within a signal
		508	handler (only relevant with %SIG - most event libraries provide safe
		509	signals).
		510
		511	That means you MUST NOT call any function that might "block" the
		512	current coroutine - "cede", "schedule" "Coro::Semaphore->down" or
		513	anything that calls those. Everything else, including calling
		514	"ready", works.
269		515
270	SEE ALSO	516	SEE ALSO
		517	Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event.
		518
		519	Debugging: Coro::Debug.
		520
271	Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util.	521	Support/Utility: Coro::Specific, Coro::Util.
272		522
273	Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore,	523	Locking and IPC: Coro::Signal, Coro::Channel, Coro::Semaphore,
274	Coro::SemaphoreSet, Coro::RWLock.	524	Coro::SemaphoreSet, Coro::RWLock.
275		525
276	Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket,	526	I/O and Timers: Coro::Timer, Coro::Handle, Coro::Socket, Coro::AIO.
		527
		528	Compatibility with other modules: Coro::LWP (but see also AnyEvent::HTTP
		529	for a better-working alternative), Coro::BDB, Coro::Storable,
277	Coro::Select.	530	Coro::Select.
278		531
279	Embedding: <Coro:MakeMaker>	532	XS API: Coro::MakeMaker.
		533
		534	Low level Configuration, Thread Environment, Continuations: Coro::State.
280		535
281	AUTHOR	536	AUTHOR
282	Marc Lehmann <schmorp@schmorp.de>	537	Marc Lehmann <schmorp@schmorp.de>
283	http://home.schmorp.de/	538	http://home.schmorp.de/
284		539

Diff Legend

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

Comparing Coro/README (file contents): Revision 1.8 by root, Thu Apr 19 10:37:26 2007 UTC vs. Revision 1.20 by root, Tue Nov 25 20:48:41 2008 UTC

Diff Legend

Comparing Coro/README (file contents):
Revision 1.8 by root, Thu Apr 19 10:37:26 2007 UTC vs.
Revision 1.20 by root, Tue Nov 25 20:48:41 2008 UTC