[ViewVC] Diff of: cvs/Coro/README

Comparing Coro/README (file contents):
Revision 1.10 by root, Fri Oct 5 10:57:40 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.
70		121
		122	The remaining arguments are passed as arguments to the closure.
		123
71	See the "Coro::State::new" constructor for info about the coroutine	124	See the "Coro::State::new" constructor for info about the coroutine
72	environment.	125	environment in which coroutines are executed.
73		126
74	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
75	outside the coroutine. Likewise, when the coroutine dies, the	128	outside the coroutine. Likewise, when the coroutine dies, the
76	program will exit, just as it would in the main program.	129	program will exit, just as it would in the main program.
77		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
78	# create a new coroutine that just prints its arguments	134	Example: Create a new coroutine that just prints its arguments.
		135
79	async {	136	async {
80	print "@_\n";	137	print "@_\n";
81	} 1,2,3,4;	138	} 1,2,3,4;
82		139
83	async_pool { ... } [@args...]	140	async_pool { ... } [@args...]
84	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
85	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
86	coroutine that might have executed other code already (which can be	143	get a coroutine that might have executed other code already (which
87	good or bad :).	144	can be good or bad :).
88		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
89	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
90	be issued in case of an exception instead of terminating the	152	be issued in case of an exception instead of terminating the
91	program, as "async" does. As the coroutine is being reused, stuff	153	program, as "async" does. As the coroutine is being reused, stuff
92	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
93	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).
94		157
95	The priority will be reset to 0 after each job, tracing will be	158	The priority will be reset to 0 after each run, tracing will be
96	disabled, the description will be reset and the default output	159	disabled, the description will be reset and the default output
97	filehandle gets restored, so you can change alkl these. Otherwise	160	filehandle gets restored, so you can change all these. Otherwise the
98	the coroutine will be re-used "as-is": most notably if you change	161	coroutine will be re-used "as-is": most notably if you change other
99	other per-coroutine global stuff such as $/ you need to revert that	162	per-coroutine global stuff such as $/ you must needs revert that
100	change, which is most simply done by using local as in " local $/ ".	163	change, which is most simply done by using local as in: "local $/".
101		164
102	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
103	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
104	coros as required.	167	non-idle coros as required.
105		168
106	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
107	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.
108	"async_pool { terminate }" once per second or so to slowly replenish	171	"async_pool { terminate }" once per second or so to slowly replenish
109	the pool. In addition to that, when the stacks used by a handler	172	the pool. In addition to that, when the stacks used by a handler
110	grows larger than 16kb (adjustable with $Coro::POOL_RSS) it will	173	grows larger than 32kb (adjustable via $Coro::POOL_RSS) it will also
111	also exit.	174	be destroyed.
		175
		176	STATIC METHODS
		177	Static methods are actually functions that implicitly operate on the
		178	current coroutine.
112		179
113	schedule	180	schedule
114	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
115	be put into the ready queue, so calling this function usually means	188	ready queue, so calling this function usually means you will never
116	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
117	handler) calls ready.	190	"->ready", thus waking you up.
118		191
119	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.
120		199
121	{	200	See HOW TO WAIT FOR A CALLBACK, below, for some ways to wait for
122	# remember current coroutine	201	callbacks.
123	my $current = $Coro::current;
124
125	# register a hypothetical event handler
126	on_event_invoke sub {
127	# wake up sleeping coroutine
128	$current->ready;
129	undef $current;
130	};
131
132	# call schedule until event occurred.
133	# in case we are woken up for other reasons
134	# (current still defined), loop.
135	Coro::schedule while $current;
136	}
137		202
138	cede	203	cede
139	"Cede" to other coroutines. This function puts the current coroutine	204	"Cede" to other coroutines. This function puts the current coroutine
140	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
141	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
142	higher priority.	207	higher priority. Once your coroutine gets its turn again it will
		208	automatically be resumed.
143		209
144	Returns true if at least one coroutine switch has happened.	210	This function is often called "yield" in other languages.
145		211
146	Coro::cede_notself	212	Coro::cede_notself
147	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
148	coroutine, regardless of priority, once.	214	any coroutine, regardless of priority. This is useful sometimes to
149		215	ensure progress is made.
150	Returns true if at least one coroutine switch has happened.
151		216
152	terminate [arg...]	217	terminate [arg...]
153	Terminates the current coroutine with the given status values (see	218	Terminates the current coroutine with the given status values (see
154	cancel).	219	cancel).
155		220
156	killall	221	killall
157	Kills/terminates/cancels all coroutines except the currently running	222	Kills/terminates/cancels all coroutines except the currently running
158	one. This is useful after a fork, either in the child or the parent,	223	one. This is useful after a fork, either in the child or the parent,
159	as usually only one of them should inherit the running coroutines.	224	as usually only one of them should inherit the running coroutines.
160		225
161	# dynamic methods	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.
162		230
163	COROUTINE METHODS	231	COROUTINE OBJECT METHODS
164	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).
165		234
166	new Coro \&sub [, @args...]	235	new Coro \&sub [, @args...]
167	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
168	coroutine automatically terminates as if "terminate" with the	237	coroutine automatically terminates as if "terminate" with the
169	returned values were called. To make the coroutine run you must	238	returned values were called. To make the coroutine run you must
170	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.
171		240
172	See "async" and "Coro::State::new" for additional info about the	241	See "async" and "Coro::State::new" for additional info about the
173	coroutine environment.	242	coroutine environment.
174		243
175	$success = $coroutine->ready	244	$success = $coroutine->ready
176	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
177	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
178	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.
179		253
180	$is_ready = $coroutine->is_ready	254	$is_ready = $coroutine->is_ready
181	Return wether the coroutine is currently the ready queue or not,	255	Return whether the coroutine is currently the ready queue or not,
182		256
183	$coroutine->cancel (arg...)	257	$coroutine->cancel (arg...)
184	Terminates the given coroutine and makes it return the given	258	Terminates the given coroutine and makes it return the given
185	arguments as status (default: the empty list). Never returns if the	259	arguments as status (default: the empty list). Never returns if the
186	coroutine is the current coroutine.	260	coroutine is the current coroutine.
187		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
188	$coroutine->join	302	$coroutine->join
189	Wait until the coroutine terminates and return any values given to	303	Wait until the coroutine terminates and return any values given to
190	the "terminate" or "cancel" functions. "join" can be called	304	the "terminate" or "cancel" functions. "join" can be called
191	concurrently from multiple coroutines.	305	concurrently from multiple coroutines, and all will be resumed and
		306	given the status return once the $coroutine terminates.
192		307
193	$coroutine->on_destroy (\&cb)	308	$coroutine->on_destroy (\&cb)
194	Registers a callback that is called when this coroutine gets	309	Registers a callback that is called when this coroutine gets
195	destroyed, but before it is joined. The callback gets passed the	310	destroyed, but before it is joined. The callback gets passed the
196	terminate arguments, if any.	311	terminate arguments, if any, and must not die, under any
		312	circumstances.
197		313
198	$oldprio = $coroutine->prio ($newprio)	314	$oldprio = $coroutine->prio ($newprio)
199	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
200	coroutine. Higher priority coroutines get run before lower priority	316	coroutine. Higher priority coroutines get run before lower priority
201	coroutines. Priorities are small signed integers (currently -4 ..	317	coroutines. Priorities are small signed integers (currently -4 ..
227	with a coroutine.	343	with a coroutine.
228		344
229	This method simply sets the "$coroutine->{desc}" member to the given	345	This method simply sets the "$coroutine->{desc}" member to the given
230	string. You can modify this member directly if you wish.	346	string. You can modify this member directly if you wish.
231		347
232	GLOBAL FUNCTIONS	348	GLOBAL FUNCTIONS
233	Coro::nready	349	Coro::nready
234	Returns the number of coroutines that are currently in the ready	350	Returns the number of coroutines that are currently in the ready
235	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
236	runnable coroutine is the currently running one, so "cede" would	352	or indirectly. The value 0 means that the only runnable coroutine is
237	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
238	is an idle handler that wakes up some coroutines.	355	that wakes up some coroutines.
239		356
240	my $guard = Coro::guard { ... }	357	my $guard = Coro::guard { ... }
241	This creates and returns a guard object. Nothing happens until the	358	This creates and returns a guard object. Nothing happens until the
242	object gets destroyed, in which case the codeblock given as argument	359	object gets destroyed, in which case the codeblock given as argument
243	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
…		…
256	# do something that requires $busy to be true	373	# do something that requires $busy to be true
257	}	374	}
258		375
259	unblock_sub { ... }	376	unblock_sub { ... }
260	This utility function takes a BLOCK or code reference and "unblocks"	377	This utility function takes a BLOCK or code reference and "unblocks"
261	it, returning the new coderef. This means that the new coderef will	378	it, returning a new coderef. Unblocking means that calling the new
262	return immediately without blocking, returning nothing, while the	379	coderef will return immediately without blocking, returning nothing,
263	original code ref will be called (with parameters) from within its	380	while the original code ref will be called (with parameters) from
264	own coroutine.	381	within another coroutine.
265		382
266	The reason this function exists is that many event libraries (such	383	The reason this function exists is that many event libraries (such
267	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
268	of thread-safety). This means you must not block within event	385	of reentrancy). This means you must not block within event
269	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.
270		389
271	This function allows your callbacks to block by executing them in	390	This function allows your callbacks to block by executing them in
272	another coroutine where it is safe to block. One example where	391	another coroutine where it is safe to block. One example where
273	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
274	results to disk.	393	results to disk, for example.
275		394
276	In short: simply use "unblock_sub { ... }" instead of "sub { ... }"	395	In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
277	when creating event callbacks that want to block.	396	when creating event callbacks that want to block.
278		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
279	BUGS/LIMITATIONS	491	BUGS/LIMITATIONS
280	- you must make very sure that no coro is still active on global	492	fork with pthread backend
281	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.
282		497
		498	perl process emulation ("threads")
283	- 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
284	from the same thread (this requirement might be loosened in the future	500	this module from the first thread (this requirement might be removed
285	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
286	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.
287		515
288	SEE ALSO	516	SEE ALSO
		517	Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event.
		518
		519	Debugging: Coro::Debug.
		520
289	Support/Utility: Coro::Specific, Coro::State, Coro::Util.	521	Support/Utility: Coro::Specific, Coro::Util.
290		522
291	Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore,	523	Locking and IPC: Coro::Signal, Coro::Channel, Coro::Semaphore,
292	Coro::SemaphoreSet, Coro::RWLock.	524	Coro::SemaphoreSet, Coro::RWLock.
293		525
294	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,
295	Coro::Select.	530	Coro::Select.
296		531
297	Embedding: <Coro:MakeMaker>	532	XS API: Coro::MakeMaker.
		533
		534	Low level Configuration, Thread Environment, Continuations: Coro::State.
298		535
299	AUTHOR	536	AUTHOR
300	Marc Lehmann <schmorp@schmorp.de>	537	Marc Lehmann <schmorp@schmorp.de>
301	http://home.schmorp.de/	538	http://home.schmorp.de/
302		539

Diff Legend

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

Comparing Coro/README (file contents): Revision 1.10 by root, Fri Oct 5 10:57:40 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.10 by root, Fri Oct 5 10:57:40 2007 UTC vs.
Revision 1.20 by root, Tue Nov 25 20:48:41 2008 UTC