[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.8 by root, Thu Apr 19 10:37:26 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.
		103
56	schedule	104	schedule
57	Calls the scheduler. Please note that the current process will not	105	Calls the scheduler. Please note that the current coroutine will not
58	be put into the ready queue, so calling this function usually means	106	be put into the ready queue, so calling this function usually means
59	you will never be called again.	107	you will never be called again unless something else (e.g. an event
		108	handler) calls ready.
		109
		110	The canonical way to wait on external events is this:
		111
		112	{
		113	# remember current coroutine
		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	}
60		128
61	cede	129	cede
62	"Cede" to other processes. This function puts the current process	130	"Cede" to other coroutines. This function puts the current coroutine
63	into the ready queue and calls "schedule", which has the effect of	131	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	132	giving up the current "timeslice" to other coroutines of the same or
65	higher priority.	133	higher priority.
66		134
		135	Returns true if at least one coroutine switch has happened.
		136
		137	Coro::cede_notself
		138	Works like cede, but is not exported by default and will cede to any
		139	coroutine, regardless of priority, once.
		140
		141	Returns true if at least one coroutine switch has happened.
		142
67	terminate [arg...]	143	terminate [arg...]
68	Terminates the current process with the given status values (see	144	Terminates the current coroutine with the given status values (see
69	cancel).	145	cancel).
70		146
71	# dynamic methods	147	# dynamic methods
72		148
73	PROCESS METHODS	149	COROUTINE METHODS
74	These are the methods you can call on process objects.	150	These are the methods you can call on coroutine objects.
75		151
76	new Coro \&sub [, @args...]	152	new Coro \&sub [, @args...]
77	Create a new process and return it. When the sub returns the process	153	Create a new coroutine and return it. When the sub returns the
78	automatically terminates as if "terminate" with the returned values	154	coroutine automatically terminates as if "terminate" with the
79	were called. To make the process run you must first put it into the	155	returned values were called. To make the coroutine run you must
80	ready queue by calling the ready method.	156	first put it into the ready queue by calling the ready method.
81		157
82	$process->ready	158	See "async" for additional discussion.
		159
		160	$success = $coroutine->ready
83	Put the given process into the ready queue.	161	Put the given coroutine into the ready queue (according to it's
		162	priority) and return true. If the coroutine is already in the ready
		163	queue, do nothing and return false.
84		164
		165	$is_ready = $coroutine->is_ready
		166	Return wether the coroutine is currently the ready queue or not,
		167
85	$process->cancel (arg...)	168	$coroutine->cancel (arg...)
86	Terminates the given process and makes it return the given arguments	169	Terminates the given coroutine and makes it return the given
87	as status (default: the empty list).	170	arguments as status (default: the empty list). Never returns if the
		171	coroutine is the current coroutine.
88		172
89	$process->join	173	$coroutine->join
90	Wait until the coroutine terminates and return any values given to	174	Wait until the coroutine terminates and return any values given to
91	the "terminate" or "cancel" functions. "join" can be called multiple	175	the "terminate" or "cancel" functions. "join" can be called multiple
92	times from multiple processes.	176	times from multiple coroutine.
93		177
		178	$coroutine->on_destroy (\&cb)
		179	Registers a callback that is called when this coroutine gets
		180	destroyed, but before it is joined. The callback gets passed the
		181	terminate arguments, if any.
		182
94	$oldprio = $process->prio($newprio)	183	$oldprio = $coroutine->prio ($newprio)
95	Sets (or gets, if the argument is missing) the priority of the	184	Sets (or gets, if the argument is missing) the priority of the
96	process. Higher priority processes get run before lower priority	185	coroutine. Higher priority coroutines get run before lower priority
97	processes. Priorities are small signed integers (currently -4 ..	186	coroutines. Priorities are small signed integers (currently -4 ..
98	+3), that you can refer to using PRIO_xxx constants (use the import	187	+3), that you can refer to using PRIO_xxx constants (use the import
99	tag :prio to get then):	188	tag :prio to get then):
100		189
101	PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN	190	PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
102	3 > 1 > 0 > -1 > -3 > -4	191	3 > 1 > 0 > -1 > -3 > -4
…		…
105	current->prio(PRIO_HIGH);	194	current->prio(PRIO_HIGH);
106		195
107	The idle coroutine ($Coro::idle) always has a lower priority than	196	The idle coroutine ($Coro::idle) always has a lower priority than
108	any existing coroutine.	197	any existing coroutine.
109		198
110	Changing the priority of the current process will take effect	199	Changing the priority of the current coroutine will take effect
111	immediately, but changing the priority of processes in the ready	200	immediately, but changing the priority of coroutines in the ready
112	queue (but not running) will only take effect after the next	201	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	202	schedule (of that coroutine). This is a bug that will be fixed in
114	future version.	203	some future version.
115		204
116	$newprio = $process->nice($change)	205	$newprio = $coroutine->nice ($change)
117	Similar to "prio", but subtract the given value from the priority	206	Similar to "prio", but subtract the given value from the priority
118	(i.e. higher values mean lower priority, just as in unix).	207	(i.e. higher values mean lower priority, just as in unix).
119		208
120	$olddesc = $process->desc($newdesc)	209	$olddesc = $coroutine->desc ($newdesc)
121	Sets (or gets in case the argument is missing) the description for	210	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	211	this coroutine. This is just a free-form string you can associate
123	a process.	212	with a coroutine.
		213
		214	GLOBAL FUNCTIONS
		215	Coro::nready
		216	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
		218	runnable coroutine is the currently running one, so "cede" would
		219	have no effect, and "schedule" would cause a deadlock unless there
		220	is an idle handler that wakes up some coroutines.
		221
		222	my $guard = Coro::guard { ... }
		223	This creates and returns a guard object. Nothing happens until the
		224	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
		226	case of a runtime error or when the coroutine gets canceled, as in
		227	both cases the guard block will be executed. The guard object
		228	supports only one method, "->cancel", which will keep the codeblock
		229	from being executed.
		230
		231	Example: set some flag and clear it again when the coroutine gets
		232	canceled or the function returns:
		233
		234	sub do_something {
		235	my $guard = Coro::guard { $busy = 0 };
		236	$busy = 1;
		237
		238	# do something that requires $busy to be true
		239	}
		240
		241	unblock_sub { ... }
		242	This utility function takes a BLOCK or code reference and "unblocks"
		243	it, returning the new coderef. This means that the new coderef will
		244	return immediately without blocking, returning nothing, while the
		245	original code ref will be called (with parameters) from within its
		246	own coroutine.
		247
		248	The reason this function exists is that many event libraries (such
		249	as the venerable Event module) are not coroutine-safe (a weaker form
		250	of thread-safety). This means you must not block within event
		251	callbacks, otherwise you might suffer from crashes or worse.
		252
		253	This function allows your callbacks to block by executing them in
		254	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
		256	results to disk.
		257
		258	In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
		259	when creating event callbacks that want to block.
124		260
125	BUGS/LIMITATIONS	261	BUGS/LIMITATIONS
126	- you must make very sure that no coro is still active on global	262	- you must make very sure that no coro is still active on global
127	destruction. very bad things might happen otherwise (usually segfaults).	263	destruction. very bad things might happen otherwise (usually segfaults).
128		264
129	- this module is not thread-safe. You should only ever use this module	265	- 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	266	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	267	to allow per-thread schedulers, but Coro::State does not yet allow
132	this).	268	this).
133		269
134	SEE ALSO	270	SEE ALSO
135	Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util.	271	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.8 by root, Thu Apr 19 10:37:26 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.8 by root, Thu Apr 19 10:37:26 2007 UTC