[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.6 by root, Sat Jan 6 02:45:56 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 use din this module also guarentees 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 essentiel 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.
		70
		71	Calling "exit" in a coroutine will not work correctly, so do not do
		72	that.
47		73
48	When the coroutine dies, the program will exit, just as in the main	74	When the coroutine dies, the program will exit, just as in the main
49	program.	75	program.
50		76
51	# create a new coroutine that just prints its arguments	77	# create a new coroutine that just prints its arguments
52	async {	78	async {
53	print "@_\n";	79	print "@_\n";
54	} 1,2,3,4;	80	} 1,2,3,4;
55		81
		82	async_pool { ... } [@args...]
		83	Similar to "async", but uses a coroutine pool, so you should not
		84	call terminate or join (although you are allowed to), and you get a
		85	coroutine that might have executed other code already (which can be
		86	good or bad :).
		87
		88	Also, the block is executed in an "eval" context and a warning will
		89	be issued in case of an exception instead of terminating the
		90	program, as "async" does. As the coroutine is being reused, stuff
		91	like "on_destroy" will not work in the expected way, unless you call
		92	terminate or cancel, which somehow defeats the purpose of pooling.
		93
		94	The priority will be reset to 0 after each job, otherwise the
		95	coroutine will be re-used "as-is".
		96
		97	The pool size is limited to 8 idle coroutines (this can be adjusted
		98	by changing $Coro::POOL_SIZE), and there can be as many non-idle
		99	coros as required.
		100
		101	If you are concerned about pooled coroutines growing a lot because a
		102	single "async_pool" used a lot of stackspace you can e.g.
		103	"async_pool { terminate }" once per second or so to slowly replenish
		104	the pool.
		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 occured.
		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	Calling "exit" in a coroutine will not work correctly, so do not do
		161	that.
		162
		163	$success = $coroutine->ready
83	Put the given process into the ready queue.	164	Put the given coroutine into the ready queue (according to it's
		165	priority) and return true. If the coroutine is already in the ready
		166	queue, do nothing and return false.
84		167
		168	$is_ready = $coroutine->is_ready
		169	Return wether the coroutine is currently the ready queue or not,
		170
85	$process->cancel (arg...)	171	$coroutine->cancel (arg...)
86	Terminates the given process and makes it return the given arguments	172	Terminates the given coroutine and makes it return the given
87	as status (default: the empty list).	173	arguments as status (default: the empty list). Never returns if the
		174	coroutine is the current coroutine.
88		175
89	$process->join	176	$coroutine->join
90	Wait until the coroutine terminates and return any values given to	177	Wait until the coroutine terminates and return any values given to
91	the "terminate" or "cancel" functions. "join" can be called multiple	178	the "terminate" or "cancel" functions. "join" can be called multiple
92	times from multiple processes.	179	times from multiple coroutine.
93		180
		181	$coroutine->on_destroy (\&cb)
		182	Registers a callback that is called when this coroutine gets
		183	destroyed, but before it is joined. The callback gets passed the
		184	terminate arguments, if any.
		185
94	$oldprio = $process->prio($newprio)	186	$oldprio = $coroutine->prio ($newprio)
95	Sets (or gets, if the argument is missing) the priority of the	187	Sets (or gets, if the argument is missing) the priority of the
96	process. Higher priority processes get run before lower priority	188	coroutine. Higher priority coroutines get run before lower priority
97	processes. Priorities are small signed integers (currently -4 ..	189	coroutines. Priorities are small signed integers (currently -4 ..
98	+3), that you can refer to using PRIO_xxx constants (use the import	190	+3), that you can refer to using PRIO_xxx constants (use the import
99	tag :prio to get then):	191	tag :prio to get then):
100		192
101	PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN	193	PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
102	3 > 1 > 0 > -1 > -3 > -4	194	3 > 1 > 0 > -1 > -3 > -4
…		…
105	current->prio(PRIO_HIGH);	197	current->prio(PRIO_HIGH);
106		198
107	The idle coroutine ($Coro::idle) always has a lower priority than	199	The idle coroutine ($Coro::idle) always has a lower priority than
108	any existing coroutine.	200	any existing coroutine.
109		201
110	Changing the priority of the current process will take effect	202	Changing the priority of the current coroutine will take effect
111	immediately, but changing the priority of processes in the ready	203	immediately, but changing the priority of coroutines in the ready
112	queue (but not running) will only take effect after the next	204	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	205	schedule (of that coroutine). This is a bug that will be fixed in
114	future version.	206	some future version.
115		207
116	$newprio = $process->nice($change)	208	$newprio = $coroutine->nice ($change)
117	Similar to "prio", but subtract the given value from the priority	209	Similar to "prio", but subtract the given value from the priority
118	(i.e. higher values mean lower priority, just as in unix).	210	(i.e. higher values mean lower priority, just as in unix).
119		211
120	$olddesc = $process->desc($newdesc)	212	$olddesc = $coroutine->desc ($newdesc)
121	Sets (or gets in case the argument is missing) the description for	213	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	214	this coroutine. This is just a free-form string you can associate
123	a process.	215	with a coroutine.
		216
		217	GLOBAL FUNCTIONS
		218	Coro::nready
		219	Returns the number of coroutines that are currently in the ready
		220	state, i.e. that can be swicthed to. The value 0 means that the only
		221	runnable coroutine is the currently running one, so "cede" would
		222	have no effect, and "schedule" would cause a deadlock unless there
		223	is an idle handler that wakes up some coroutines.
		224
		225	my $guard = Coro::guard { ... }
		226	This creates and returns a guard object. Nothing happens until the
		227	objetc gets destroyed, in which case the codeblock given as argument
		228	will be executed. This is useful to free locks or other resources in
		229	case of a runtime error or when the coroutine gets canceled, as in
		230	both cases the guard block will be executed. The guard object
		231	supports only one method, "->cancel", which will keep the codeblock
		232	from being executed.
		233
		234	Example: set some flag and clear it again when the coroutine gets
		235	canceled or the function returns:
		236
		237	sub do_something {
		238	my $guard = Coro::guard { $busy = 0 };
		239	$busy = 1;
		240
		241	# do something that requires $busy to be true
		242	}
		243
		244	unblock_sub { ... }
		245	This utility function takes a BLOCK or code reference and "unblocks"
		246	it, returning the new coderef. This means that the new coderef will
		247	return immediately without blocking, returning nothing, while the
		248	original code ref will be called (with parameters) from within its
		249	own coroutine.
		250
		251	The reason this fucntion exists is that many event libraries (such
		252	as the venerable Event module) are not coroutine-safe (a weaker form
		253	of thread-safety). This means you must not block within event
		254	callbacks, otherwise you might suffer from crashes or worse.
		255
		256	This function allows your callbacks to block by executing them in
		257	another coroutine where it is safe to block. One example where
		258	blocking is handy is when you use the Coro::AIO functions to save
		259	results to disk.
		260
		261	In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
		262	when creating event callbacks that want to block.
124		263
125	BUGS/LIMITATIONS	264	BUGS/LIMITATIONS
126	- you must make very sure that no coro is still active on global	265	- you must make very sure that no coro is still active on global
127	destruction. very bad things might happen otherwise (usually segfaults).	266	destruction. very bad things might happen otherwise (usually segfaults).
128		267

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.6 by root, Sat Jan 6 02:45:56 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.6 by root, Sat Jan 6 02:45:56 2007 UTC