[ViewVC] Diff of: cvs/Coro/README

Comparing Coro/README (file contents):
Revision 1.3 by root, Mon Nov 6 19:56:26 2006 UTC vs.
Revision 1.9 by root, Sat Sep 29 19:42:08 2007 UTC

…		…
6		6
7	async {	7	async {
8	# some asynchronous thread of execution	8	# some asynchronous thread of execution
9	};	9	};
10		10
11	# alternatively create an async process like this:	11	# alternatively create an async coroutine like this:
12		12
13	sub some_func : Coro {	13	sub some_func : Coro {
14	# some more async code	14	# some more async code
15	}	15	}
16		16
17	cede;	17	cede;
18		18
19	DESCRIPTION	19	DESCRIPTION
20	This module collection manages coroutines. Coroutines are similar to	20	This module collection manages coroutines. Coroutines are similar to
21	threads but don't run in parallel.	21	threads but don't run in parallel at the same time even on SMP machines.
		22	The specific flavor of coroutine used in this module also guarantees you
		23	that it will not switch between coroutines unless necessary, at
		24	easily-identified points in your program, so locking and parallel access
		25	are rarely an issue, making coroutine programming much safer than
		26	threads programming.
		27
		28	(Perl, however, does not natively support real threads but instead does
		29	a very slow and memory-intensive emulation of processes using threads.
		30	This is a performance win on Windows machines, and a loss everywhere
		31	else).
22		32
23	In this module, coroutines are defined as "callchain + lexical variables	33	In this module, coroutines are defined as "callchain + lexical variables
24	+ @_ + $_ + $@ + $^W + C stack), that is, a coroutine has it's own	34	+ @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own
25	callchain, it's own set of lexicals and it's own set of perl's most	35	callchain, its own set of lexicals and its own set of perls most
26	important global variables.	36	important global variables.
27		37
28	$main	38	$main
29	This coroutine represents the main program.	39	This coroutine represents the main program.
30		40
31	$current (or as function: current)	41	$current (or as function: current)
32	The current coroutine (the last coroutine switched to). The initial	42	The current coroutine (the last coroutine switched to). The initial
33	value is $main (of course).	43	value is $main (of course).
34		44
		45	This variable is strictly read-only. It is provided for
		46	performance reasons. If performance is not essential you are
		47	encouraged to use the "Coro::current" function instead.
		48
35	$idle	49	$idle
36	The coroutine to switch to when no other coroutine is running. The	50	A callback that is called whenever the scheduler finds no ready
37	default implementation prints "FATAL: deadlock detected" and exits.	51	coroutines to run. The default implementation prints "FATAL:
		52	deadlock detected" and exits, because the program has no other way
		53	to continue.
		54
		55	This hook is overwritten by modules such as "Coro::Timer" and
		56	"Coro::Event" to wait on an external event that hopefully wake up a
		57	coroutine so the scheduler can run it.
		58
		59	Please note that if your callback recursively invokes perl (e.g. for
		60	event handlers), then it must be prepared to be called recursively.
38		61
39	STATIC METHODS	62	STATIC METHODS
40	Static methods are actually functions that operate on the current	63	Static methods are actually functions that operate on the current
41	process only.	64	coroutine only.
42		65
43	async { ... } [@args...]	66	async { ... } [@args...]
44	Create a new asynchronous process and return it's process object	67	Create a new asynchronous coroutine and return it's coroutine object
45	(usually unused). When the sub returns the new process is	68	(usually unused). When the sub returns the new coroutine is
46	automatically terminated.	69	automatically terminated.
47		70
48	When the coroutine dies, the program will exit, just as in the main	71	Calling "exit" in a coroutine will do the same as calling exit
49	program.	72	outside the coroutine. Likewise, when the coroutine dies, the
		73	program will exit, just as it would in the main program.
50		74
51	# create a new coroutine that just prints its arguments	75	# create a new coroutine that just prints its arguments
52	async {	76	async {
53	print "@_\n";	77	print "@_\n";
54	} 1,2,3,4;	78	} 1,2,3,4;
55		79
		80	async_pool { ... } [@args...]
		81	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
		83	coroutine that might have executed other code already (which can be
		84	good or bad :).
		85
		86	Also, the block is executed in an "eval" context and a warning will
		87	be issued in case of an exception instead of terminating the
		88	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
		90	terminate or cancel, which somehow defeats the purpose of pooling.
		91
		92	The priority will be reset to 0 after each job, otherwise the
		93	coroutine will be re-used "as-is".
		94
		95	The pool size is limited to 8 idle coroutines (this can be adjusted
		96	by changing $Coro::POOL_SIZE), and there can be as many non-idle
		97	coros as required.
		98
		99	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.
		101	"async_pool { terminate }" once per second or so to slowly replenish
		102	the pool. In addition to that, when the stacks used by a handler
		103	grows larger than 16kb (adjustable with $Coro::POOL_RSS) it will
		104	also exit.
		105
56	schedule	106	schedule
57	Calls the scheduler. Please note that the current process will not	107	Calls the scheduler. Please note that the current coroutine will not
58	be put into the ready queue, so calling this function usually means	108	be put into the ready queue, so calling this function usually means
59	you will never be called again.	109	you will never be called again unless something else (e.g. an event
		110	handler) calls ready.
		111
		112	The canonical way to wait on external events is this:
		113
		114	{
		115	# remember current coroutine
		116	my $current = $Coro::current;
		117
		118	# register a hypothetical event handler
		119	on_event_invoke sub {
		120	# wake up sleeping coroutine
		121	$current->ready;
		122	undef $current;
		123	};
		124
		125	# call schedule until event occurred.
		126	# in case we are woken up for other reasons
		127	# (current still defined), loop.
		128	Coro::schedule while $current;
		129	}
60		130
61	cede	131	cede
62	"Cede" to other processes. This function puts the current process	132	"Cede" to other coroutines. This function puts the current coroutine
63	into the ready queue and calls "schedule", which has the effect of	133	into the ready queue and calls "schedule", which has the effect of
64	giving up the current "timeslice" to other coroutines of the same or	134	giving up the current "timeslice" to other coroutines of the same or
65	higher priority.	135	higher priority.
66		136
		137	Returns true if at least one coroutine switch has happened.
		138
		139	Coro::cede_notself
		140	Works like cede, but is not exported by default and will cede to any
		141	coroutine, regardless of priority, once.
		142
		143	Returns true if at least one coroutine switch has happened.
		144
67	terminate [arg...]	145	terminate [arg...]
68	Terminates the current process with the given status values (see	146	Terminates the current coroutine with the given status values (see
69	cancel).	147	cancel).
70		148
71	# dynamic methods	149	# dynamic methods
72		150
73	PROCESS METHODS	151	COROUTINE METHODS
74	These are the methods you can call on process objects.	152	These are the methods you can call on coroutine objects.
75		153
76	new Coro \&sub [, @args...]	154	new Coro \&sub [, @args...]
77	Create a new process and return it. When the sub returns the process	155	Create a new coroutine and return it. When the sub returns the
78	automatically terminates as if "terminate" with the returned values	156	coroutine automatically terminates as if "terminate" with the
79	were called. To make the process run you must first put it into the	157	returned values were called. To make the coroutine run you must
80	ready queue by calling the ready method.	158	first put it into the ready queue by calling the ready method.
81		159
82	$process->ready	160	See "async" for additional discussion.
		161
		162	$success = $coroutine->ready
83	Put the given process into the ready queue.	163	Put the given coroutine into the ready queue (according to it's
		164	priority) and return true. If the coroutine is already in the ready
		165	queue, do nothing and return false.
84		166
		167	$is_ready = $coroutine->is_ready
		168	Return wether the coroutine is currently the ready queue or not,
		169
85	$process->cancel (arg...)	170	$coroutine->cancel (arg...)
86	Terminates the given process and makes it return the given arguments	171	Terminates the given coroutine and makes it return the given
87	as status (default: the empty list).	172	arguments as status (default: the empty list). Never returns if the
		173	coroutine is the current coroutine.
88		174
89	$process->join	175	$coroutine->join
90	Wait until the coroutine terminates and return any values given to	176	Wait until the coroutine terminates and return any values given to
91	the "terminate" or "cancel" functions. "join" can be called multiple	177	the "terminate" or "cancel" functions. "join" can be called multiple
92	times from multiple processes.	178	times from multiple coroutine.
93		179
		180	$coroutine->on_destroy (\&cb)
		181	Registers a callback that is called when this coroutine gets
		182	destroyed, but before it is joined. The callback gets passed the
		183	terminate arguments, if any.
		184
94	$oldprio = $process->prio($newprio)	185	$oldprio = $coroutine->prio ($newprio)
95	Sets (or gets, if the argument is missing) the priority of the	186	Sets (or gets, if the argument is missing) the priority of the
96	process. Higher priority processes get run before lower priority	187	coroutine. Higher priority coroutines get run before lower priority
97	processes. Priorities are small signed integers (currently -4 ..	188	coroutines. Priorities are small signed integers (currently -4 ..
98	+3), that you can refer to using PRIO_xxx constants (use the import	189	+3), that you can refer to using PRIO_xxx constants (use the import
99	tag :prio to get then):	190	tag :prio to get then):
100		191
101	PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN	192	PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
102	3 > 1 > 0 > -1 > -3 > -4	193	3 > 1 > 0 > -1 > -3 > -4
…		…
105	current->prio(PRIO_HIGH);	196	current->prio(PRIO_HIGH);
106		197
107	The idle coroutine ($Coro::idle) always has a lower priority than	198	The idle coroutine ($Coro::idle) always has a lower priority than
108	any existing coroutine.	199	any existing coroutine.
109		200
110	Changing the priority of the current process will take effect	201	Changing the priority of the current coroutine will take effect
111	immediately, but changing the priority of processes in the ready	202	immediately, but changing the priority of coroutines in the ready
112	queue (but not running) will only take effect after the next	203	queue (but not running) will only take effect after the next
113	schedule (of that process). This is a bug that will be fixed in some	204	schedule (of that coroutine). This is a bug that will be fixed in
114	future version.	205	some future version.
115		206
116	$newprio = $process->nice($change)	207	$newprio = $coroutine->nice ($change)
117	Similar to "prio", but subtract the given value from the priority	208	Similar to "prio", but subtract the given value from the priority
118	(i.e. higher values mean lower priority, just as in unix).	209	(i.e. higher values mean lower priority, just as in unix).
119		210
120	$olddesc = $process->desc($newdesc)	211	$olddesc = $coroutine->desc ($newdesc)
121	Sets (or gets in case the argument is missing) the description for	212	Sets (or gets in case the argument is missing) the description for
122	this process. This is just a free-form string you can associate with	213	this coroutine. This is just a free-form string you can associate
123	a process.	214	with a coroutine.
		215
		216	GLOBAL FUNCTIONS
		217	Coro::nready
		218	Returns the number of coroutines that are currently in the ready
		219	state, i.e. that can be switched to. The value 0 means that the only
		220	runnable coroutine is the currently running one, so "cede" would
		221	have no effect, and "schedule" would cause a deadlock unless there
		222	is an idle handler that wakes up some coroutines.
		223
		224	my $guard = Coro::guard { ... }
		225	This creates and returns a guard object. Nothing happens until the
		226	object gets destroyed, in which case the codeblock given as argument
		227	will be executed. This is useful to free locks or other resources in
		228	case of a runtime error or when the coroutine gets canceled, as in
		229	both cases the guard block will be executed. The guard object
		230	supports only one method, "->cancel", which will keep the codeblock
		231	from being executed.
		232
		233	Example: set some flag and clear it again when the coroutine gets
		234	canceled or the function returns:
		235
		236	sub do_something {
		237	my $guard = Coro::guard { $busy = 0 };
		238	$busy = 1;
		239
		240	# do something that requires $busy to be true
		241	}
		242
		243	unblock_sub { ... }
		244	This utility function takes a BLOCK or code reference and "unblocks"
		245	it, returning the new coderef. This means that the new coderef will
		246	return immediately without blocking, returning nothing, while the
		247	original code ref will be called (with parameters) from within its
		248	own coroutine.
		249
		250	The reason this function exists is that many event libraries (such
		251	as the venerable Event module) are not coroutine-safe (a weaker form
		252	of thread-safety). This means you must not block within event
		253	callbacks, otherwise you might suffer from crashes or worse.
		254
		255	This function allows your callbacks to block by executing them in
		256	another coroutine where it is safe to block. One example where
		257	blocking is handy is when you use the Coro::AIO functions to save
		258	results to disk.
		259
		260	In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
		261	when creating event callbacks that want to block.
124		262
125	BUGS/LIMITATIONS	263	BUGS/LIMITATIONS
126	- you must make very sure that no coro is still active on global	264	- you must make very sure that no coro is still active on global
127	destruction. very bad things might happen otherwise (usually segfaults).	265	destruction. very bad things might happen otherwise (usually segfaults).
128		266
129	- this module is not thread-safe. You should only ever use this module	267	- this module is not thread-safe. You should only ever use this module
130	from the same thread (this requirement might be losened in the future	268	from the same thread (this requirement might be loosened in the future
131	to allow per-thread schedulers, but Coro::State does not yet allow	269	to allow per-thread schedulers, but Coro::State does not yet allow
132	this).	270	this).
133		271
134	SEE ALSO	272	SEE ALSO
135	Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util.	273	Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util.

Diff Legend

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

Comparing Coro/README (file contents): Revision 1.3 by root, Mon Nov 6 19:56:26 2006 UTC vs. Revision 1.9 by root, Sat Sep 29 19:42:08 2007 UTC

Diff Legend

Comparing Coro/README (file contents):
Revision 1.3 by root, Mon Nov 6 19:56:26 2006 UTC vs.
Revision 1.9 by root, Sat Sep 29 19:42:08 2007 UTC