[ViewVC] Diff of: cvs/Coro/README

Comparing Coro/README (file contents):
Revision 1.14 by root, Sat May 10 22:32:40 2008 UTC vs.
Revision 1.18 by root, Thu Nov 20 09:37:21 2008 UTC

…		…
14	cede; # yield to coroutine	14	cede; # yield to coroutine
15	print "3\n";	15	print "3\n";
16	cede; # and again	16	cede; # and again
17		17
18	# use locking	18	# use locking
		19	use Coro::Semaphore;
19	my $lock = new Coro::Semaphore;	20	my $lock = new Coro::Semaphore;
20	my $locked;	21	my $locked;
21		22
22	$lock->down;	23	$lock->down;
23	$locked = 1;	24	$locked = 1;
…		…
53		54
54	$Coro::main	55	$Coro::main
55	This variable stores the coroutine object that represents the main	56	This variable stores the coroutine object that represents the main
56	program. While you cna "ready" it and do most other things you can	57	program. While you cna "ready" it and do most other things you can
57	do to coroutines, it is mainly useful to compare again	58	do to coroutines, it is mainly useful to compare again
58	$Coro::current, to see wether you are running in the main program or	59	$Coro::current, to see whether you are running in the main program
59	not.	60	or not.
60		61
61	$Coro::current	62	$Coro::current
62	The coroutine object representing the current coroutine (the last	63	The coroutine object representing the current coroutine (the last
63	coroutine that the Coro scheduler switched to). The initial value is	64	coroutine that the Coro scheduler switched to). The initial value is
64	$main (of course).	65	$Coro::main (of course).
65		66
66	This variable is strictly read-only. You can take copies of the	67	This variable is strictly read-only. You can take copies of the
67	value stored in it and use it as any other coroutine object, but you	68	value stored in it and use it as any other coroutine object, but you
68	must not otherwise modify the variable itself.	69	must not otherwise modify the variable itself.
69		70
…		…
125	Similar to "async", but uses a coroutine pool, so you should not	126	Similar to "async", but uses a coroutine pool, so you should not
126	call terminate or join on it (although you are allowed to), and you	127	call terminate or join on it (although you are allowed to), and you
127	get a coroutine that might have executed other code already (which	128	get a coroutine that might have executed other code already (which
128	can be good or bad :).	129	can be good or bad :).
129		130
130	On the plus side, this function is faster than creating (and	131	On the plus side, this function is about twice as fast as creating
131	destroying) a completely new coroutine, so if you need a lot of	132	(and destroying) a completely new coroutine, so if you need a lot of
132	generic coroutines in quick successsion, use "async_pool", not	133	generic coroutines in quick successsion, use "async_pool", not
133	"async".	134	"async".
134		135
135	The code block is executed in an "eval" context and a warning will	136	The code block is executed in an "eval" context and a warning will
136	be issued in case of an exception instead of terminating the	137	be issued in case of an exception instead of terminating the
…		…
141		142
142	The priority will be reset to 0 after each run, tracing will be	143	The priority will be reset to 0 after each run, tracing will be
143	disabled, the description will be reset and the default output	144	disabled, the description will be reset and the default output
144	filehandle gets restored, so you can change all these. Otherwise the	145	filehandle gets restored, so you can change all these. Otherwise the
145	coroutine will be re-used "as-is": most notably if you change other	146	coroutine will be re-used "as-is": most notably if you change other
146	per-coroutine global stuff such as $/ you must needs to revert	147	per-coroutine global stuff such as $/ you must needs revert that
147	that change, which is most simply done by using local as in: " local	148	change, which is most simply done by using local as in: "local $/".
148	$/ ".
149		149
150	The pool size is limited to 8 idle coroutines (this can be adjusted	150	The idle pool size is limited to 8 idle coroutines (this can be
151	by changing $Coro::POOL_SIZE), and there can be as many non-idle	151	adjusted by changing $Coro::POOL_SIZE), but there can be as many
152	coros as required.	152	non-idle coros as required.
153		153
154	If you are concerned about pooled coroutines growing a lot because a	154	If you are concerned about pooled coroutines growing a lot because a
155	single "async_pool" used a lot of stackspace you can e.g.	155	single "async_pool" used a lot of stackspace you can e.g.
156	"async_pool { terminate }" once per second or so to slowly replenish	156	"async_pool { terminate }" once per second or so to slowly replenish
157	the pool. In addition to that, when the stacks used by a handler	157	the pool. In addition to that, when the stacks used by a handler
…		…
177	This makes "schedule" the generic method to use to block the	177	This makes "schedule" the generic method to use to block the
178	current coroutine and wait for events: first you remember the	178	current coroutine and wait for events: first you remember the
179	current coroutine in a variable, then arrange for some callback of	179	current coroutine in a variable, then arrange for some callback of
180	yours to call "->ready" on that once some event happens, and last	180	yours to call "->ready" on that once some event happens, and last
181	you call "schedule" to put yourself to sleep. Note that a lot of	181	you call "schedule" to put yourself to sleep. Note that a lot of
182	things can wake your coroutine up, so you need to check wether the	182	things can wake your coroutine up, so you need to check whether the
183	event indeed happened, e.g. by storing the status in a variable.	183	event indeed happened, e.g. by storing the status in a variable.
184		184
185	The canonical way to wait on external events is this:	185	See HOW TO WAIT FOR A CALLBACK, below, for some ways to wait for
186		186	callbacks.
187	{
188	# remember current coroutine
189	my $current = $Coro::current;
190
191	# register a hypothetical event handler
192	on_event_invoke sub {
193	# wake up sleeping coroutine
194	$current->ready;
195	undef $current;
196	};
197
198	# call schedule until event occurred.
199	# in case we are woken up for other reasons
200	# (current still defined), loop.
201	Coro::schedule while $current;
202	}
203		187
204	cede	188	cede
205	"Cede" to other coroutines. This function puts the current coroutine	189	"Cede" to other coroutines. This function puts the current coroutine
206	into the ready queue and calls "schedule", which has the effect of	190	into the ready queue and calls "schedule", which has the effect of
207	giving up the current "timeslice" to other coroutines of the same or	191	giving up the current "timeslice" to other coroutines of the same or
…		…
223	Kills/terminates/cancels all coroutines except the currently running	207	Kills/terminates/cancels all coroutines except the currently running
224	one. This is useful after a fork, either in the child or the parent,	208	one. This is useful after a fork, either in the child or the parent,
225	as usually only one of them should inherit the running coroutines.	209	as usually only one of them should inherit the running coroutines.
226		210
227	Note that while this will try to free some of the main programs	211	Note that while this will try to free some of the main programs
228	resources, you cnanot free all of them, so if a coroutine that is	212	resources, you cannot free all of them, so if a coroutine that is
229	not the main program calls this function, there will be some	213	not the main program calls this function, there will be some
230	one-time resource leak.	214	one-time resource leak.
231		215
232	COROUTINE METHODS	216	COROUTINE METHODS
233	These are the methods you can call on coroutine objects (or to create	217	These are the methods you can call on coroutine objects (or to create
…		…
251	automatically once all the coroutines of higher priority and all	235	automatically once all the coroutines of higher priority and all
252	coroutines of the same priority that were put into the ready queue	236	coroutines of the same priority that were put into the ready queue
253	earlier have been resumed.	237	earlier have been resumed.
254		238
255	$is_ready = $coroutine->is_ready	239	$is_ready = $coroutine->is_ready
256	Return wether the coroutine is currently the ready queue or not,	240	Return whether the coroutine is currently the ready queue or not,
257		241
258	$coroutine->cancel (arg...)	242	$coroutine->cancel (arg...)
259	Terminates the given coroutine and makes it return the given	243	Terminates the given coroutine and makes it return the given
260	arguments as status (default: the empty list). Never returns if the	244	arguments as status (default: the empty list). Never returns if the
261	coroutine is the current coroutine.	245	coroutine is the current coroutine.
		246
		247	$coroutine->schedule_to
		248	Puts the current coroutine to sleep (like "Coro::schedule"), but
		249	instead of continuing with the next coro from the ready queue,
		250	always switch to the given coroutine object (regardless of priority
		251	etc.). The readyness state of that coroutine isn't changed.
		252
		253	This is an advanced method for special cases - I'd love to hear
		254	about any uses for this one.
		255
		256	$coroutine->cede_to
		257	Like "schedule_to", but puts the current coroutine into the ready
		258	queue. This has the effect of temporarily switching to the given
		259	coroutine, and continuing some time later.
		260
		261	This is an advanced method for special cases - I'd love to hear
		262	about any uses for this one.
		263
		264	$coroutine->throw ([$scalar])
		265	If $throw is specified and defined, it will be thrown as an
		266	exception inside the coroutine at the next convenient point in time.
		267	Otherwise clears the exception object.
		268
		269	Coro will check for the exception each time a schedule-like-function
		270	returns, i.e. after each "schedule", "cede",
		271	"Coro::Semaphore->down", "Coro::Handle->readable" and so on. Most of
		272	these functions detect this case and return early in case an
		273	exception is pending.
		274
		275	The exception object will be thrown "as is" with the specified
		276	scalar in $@, i.e. if it is a string, no line number or newline will
		277	be appended (unlike with "die").
		278
		279	This can be used as a softer means than "cancel" to ask a coroutine
		280	to end itself, although there is no guarantee that the exception
		281	will lead to termination, and if the exception isn't caught it might
		282	well end the whole program.
		283
		284	You might also think of "throw" as being the moral equivalent of
		285	"kill"ing a coroutine with a signal (in this case, a scalar).
262		286
263	$coroutine->join	287	$coroutine->join
264	Wait until the coroutine terminates and return any values given to	288	Wait until the coroutine terminates and return any values given to
265	the "terminate" or "cancel" functions. "join" can be called	289	the "terminate" or "cancel" functions. "join" can be called
266	concurrently from multiple coroutines, and all will be resumed and	290	concurrently from multiple coroutines, and all will be resumed and
…		…
303	this coroutine. This is just a free-form string you can associate	327	this coroutine. This is just a free-form string you can associate
304	with a coroutine.	328	with a coroutine.
305		329
306	This method simply sets the "$coroutine->{desc}" member to the given	330	This method simply sets the "$coroutine->{desc}" member to the given
307	string. You can modify this member directly if you wish.	331	string. You can modify this member directly if you wish.
308
309	$coroutine->throw ([$scalar])
310	If $throw is specified and defined, it will be thrown as an
311	exception inside the coroutine at the next convinient point in time
312	(usually after it gains control at the next schedule/transfer/cede).
313	Otherwise clears the exception object.
314
315	The exception object will be thrown "as is" with the specified
316	scalar in $@, i.e. if it is a string, no line number or newline will
317	be appended (unlike with "die").
318
319	This can be used as a softer means than "cancel" to ask a coroutine
320	to end itself, although there is no guarentee that the exception
321	will lead to termination, and if the exception isn't caught it might
322	well end the whole program.
323		332
324	GLOBAL FUNCTIONS	333	GLOBAL FUNCTIONS
325	Coro::nready	334	Coro::nready
326	Returns the number of coroutines that are currently in the ready	335	Returns the number of coroutines that are currently in the ready
327	state, i.e. that can be switched to by calling "schedule" directory	336	state, i.e. that can be switched to by calling "schedule" directory
…		…
380	when you use a module that uses AnyEvent (and you use	389	when you use a module that uses AnyEvent (and you use
381	Coro::AnyEvent) and it provides callbacks that are the result of	390	Coro::AnyEvent) and it provides callbacks that are the result of
382	some event callback, then you must not block either, or use	391	some event callback, then you must not block either, or use
383	"unblock_sub".	392	"unblock_sub".
384		393
		394	$cb = Coro::rouse_cb
		395	Create and return a "rouse callback". That's a code reference that,
		396	when called, will save its arguments and notify the owner coroutine
		397	of the callback.
		398
		399	See the next function.
		400
		401	@args = Coro::rouse_wait [$cb]
		402	Wait for the specified rouse callback (or the last one tht was
		403	created in this coroutine).
		404
		405	As soon as the callback is invoked (or when the calback was invoked
		406	before "rouse_wait"), it will return a copy of the arguments
		407	originally passed to the rouse callback.
		408
		409	See the section HOW TO WAIT FOR A CALLBACK for an actual usage
		410	example.
		411
		412	HOW TO WAIT FOR A CALLBACK
		413	It is very common for a coroutine to wait for some callback to be
		414	called. This occurs naturally when you use coroutines in an otherwise
		415	event-based program, or when you use event-based libraries.
		416
		417	These typically register a callback for some event, and call that
		418	callback when the event occured. In a coroutine, however, you typically
		419	want to just wait for the event, simplyifying things.
		420
		421	For example "AnyEvent->child" registers a callback to be called when a
		422	specific child has exited:
		423
		424	my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... });
		425
		426	But from withina coroutine, you often just want to write this:
		427
		428	my $status = wait_for_child $pid;
		429
		430	Coro offers two functions specifically designed to make this easy,
		431	"Coro::rouse_cb" and "Coro::rouse_wait".
		432
		433	The first function, "rouse_cb", generates and returns a callback that,
		434	when invoked, will save it's arguments and notify the coroutine that
		435	created the callback.
		436
		437	The second function, "rouse_wait", waits for the callback to be called
		438	(by calling "schedule" to go to sleep) and returns the arguments
		439	originally passed to the callback.
		440
		441	Using these functions, it becomes easy to write the "wait_for_child"
		442	function mentioned above:
		443
		444	sub wait_for_child($) {
		445	my ($pid) = @_;
		446
		447	my $watcher = AnyEvent->child (pid => $pid, cb => Coro::rouse_cb);
		448
		449	my ($rpid, $rstatus) = Coro::rouse_wait;
		450	$rstatus
		451	}
		452
		453	In the case where "rouse_cb" and "rouse_wait" are not flexible enough,
		454	you can roll your own, using "schedule":
		455
		456	sub wait_for_child($) {
		457	my ($pid) = @_;
		458
		459	# store the current coroutine in $current,
		460	# and provide result variables for the closure passed to ->child
		461	my $current = $Coro::current;
		462	my ($done, $rstatus);
		463
		464	# pass a closure to ->child
		465	my $watcher = AnyEvent->child (pid => $pid, cb => sub {
		466	$rstatus = $_[1]; # remember rstatus
		467	$done = 1; # mark $rstatus as valud
		468	});
		469
		470	# wait until the closure has been called
		471	schedule while !$done;
		472
		473	$rstatus
		474	}
		475
385	BUGS/LIMITATIONS	476	BUGS/LIMITATIONS
		477	fork with pthread backend
		478	When Coro is compiled using the pthread backend (which isn't
		479	recommended but required on many BSDs as their libcs are completely
		480	broken), then coroutines will not survive a fork. There is no known
		481	workaround except to fix your libc and use a saner backend.
		482
		483	perl process emulation ("threads")
386	This module is not perl-pseudo-thread-safe. You should only ever use	484	This module is not perl-pseudo-thread-safe. You should only ever use
387	this module from the same thread (this requirement might be removed in	485	this module from the same thread (this requirement might be removed
388	the future to allow per-thread schedulers, but Coro::State does not yet	486	in the future to allow per-thread schedulers, but Coro::State does
389	allow this). I recommend disabling thread support and using processes,	487	not yet allow this). I recommend disabling thread support and using
390	as this is much faster and uses less memory.	488	processes, as having the windows process emulation enabled under
		489	unix roughly halves perl performance, even when not used.
		490
		491	coroutine switching not signal safe
		492	You must not switch to another coroutine from within a signal
		493	handler (only relevant with %SIG - most event libraries provide safe
		494	signals).
		495
		496	That means you MUST NOT call any function that might "block" the
		497	current coroutine - "cede", "schedule" "Coro::Semaphore->down" or
		498	anything that calls those. Everything else, including calling
		499	"ready", works.
391		500
392	SEE ALSO	501	SEE ALSO
393	Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event.	502	Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event.
394		503
395	Debugging: Coro::Debug.	504	Debugging: Coro::Debug.

Diff Legend

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

Comparing Coro/README (file contents): Revision 1.14 by root, Sat May 10 22:32:40 2008 UTC vs. Revision 1.18 by root, Thu Nov 20 09:37:21 2008 UTC

Diff Legend

Comparing Coro/README (file contents):
Revision 1.14 by root, Sat May 10 22:32:40 2008 UTC vs.
Revision 1.18 by root, Thu Nov 20 09:37:21 2008 UTC