[ViewVC] Diff of: cvs/Coro/README

Comparing Coro/README (file contents):
Revision 1.27 by root, Fri Dec 25 07:17:12 2009 UTC vs.
Revision 1.29 by root, Sat Feb 19 06:51:22 2011 UTC

…		…
38	are rarely an issue, making thread programming much safer and easier	38	are rarely an issue, making thread programming much safer and easier
39	than using other thread models.	39	than using other thread models.
40		40
41	Unlike the so-called "Perl threads" (which are not actually real threads	41	Unlike the so-called "Perl threads" (which are not actually real threads
42	but only the windows process emulation (see section of same name for	42	but only the windows process emulation (see section of same name for
43	more details) ported to unix, and as such act as processes), Coro	43	more details) ported to UNIX, and as such act as processes), Coro
44	provides a full shared address space, which makes communication between	44	provides a full shared address space, which makes communication between
45	threads very easy. And Coro's threads are fast, too: disabling the	45	threads very easy. And coro threads are fast, too: disabling the Windows
46	Windows process emulation code in your perl and using Coro can easily	46	process emulation code in your perl and using Coro can easily result in
47	result in a two to four times speed increase for your programs. A	47	a two to four times speed increase for your programs. A parallel matrix
48	parallel matrix multiplication benchmark runs over 300 times faster on a	48	multiplication benchmark (very communication-intensive) runs over 300
49	single core than perl's pseudo-threads on a quad core using all four	49	times faster on a single core than perls pseudo-threads on a quad core
50	cores.	50	using all four cores.
51		51
52	Coro achieves that by supporting multiple running interpreters that	52	Coro achieves that by supporting multiple running interpreters that
53	share data, which is especially useful to code pseudo-parallel processes	53	share data, which is especially useful to code pseudo-parallel processes
54	and for event-based programming, such as multiple HTTP-GET requests	54	and for event-based programming, such as multiple HTTP-GET requests
55	running concurrently. See Coro::AnyEvent to learn more on how to	55	running concurrently. See Coro::AnyEvent to learn more on how to
…		…
61	important global variables (see Coro::State for more configuration and	61	important global variables (see Coro::State for more configuration and
62	background info).	62	background info).
63		63
64	See also the "SEE ALSO" section at the end of this document - the Coro	64	See also the "SEE ALSO" section at the end of this document - the Coro
65	module family is quite large.	65	module family is quite large.
		66
		67	CORO THREAD LIFE CYCLE
		68	During the long and exciting (or not) life of a coro thread, it goes
		69	through a number of states:
		70
		71	1. Creation
		72	The first thing in the life of a coro thread is it's creation -
		73	obviously. The typical way to create a thread is to call the "async
		74	BLOCK" function:
		75
		76	async {
		77	# thread code goes here
		78	};
		79
		80	You can also pass arguments, which are put in @_:
		81
		82	async {
		83	print $_[1]; # prints 2
		84	} 1, 2, 3;
		85
		86	This creates a new coro thread and puts it into the ready queue,
		87	meaning it will run as soon as the CPU is free for it.
		88
		89	"async" will return a coro object - you can store this for future
		90	reference or ignore it, the thread itself will keep a reference to
		91	it's thread object - threads are alive on their own.
		92
		93	Another way to create a thread is to call the "new" constructor with
		94	a code-reference:
		95
		96	new Coro sub {
		97	# thread code goes here
		98	}, @optional_arguments;
		99
		100	This is quite similar to calling "async", but the important
		101	difference is that the new thread is not put into the ready queue,
		102	so the thread will not run until somebody puts it there. "async" is,
		103	therefore, identical to this sequence:
		104
		105	my $coro = new Coro sub {
		106	# thread code goes here
		107	};
		108	$coro->ready;
		109	return $coro;
		110
		111	2. Startup
		112	When a new coro thread is created, only a copy of the code reference
		113	and the arguments are stored, no extra memory for stacks and so on
		114	is allocated, keeping the coro thread in a low-memory state.
		115
		116	Only when it actually starts executing will all the resources be
		117	finally allocated.
		118
		119	The optional arguments specified at coro creation are available in
		120	@_, similar to function calls.
		121
		122	3. Running / Blocking
		123	A lot can happen after the coro thread has started running. Quite
		124	usually, it will not run to the end in one go (because you could use
		125	a function instead), but it will give up the CPU regularly because
		126	it waits for external events.
		127
		128	As long as a coro thread runs, it's coro object is available in the
		129	global variable $Coro::current.
		130
		131	The low-level way to give up the CPU is to call the scheduler, which
		132	selects a new coro thread to run:
		133
		134	Coro::schedule;
		135
		136	Since running threads are not in the ready queue, calling the
		137	scheduler without doing anything else will block the coro thread
		138	forever - you need to arrange either for the coro to put woken up
		139	(readied) by some other event or some other thread, or you can put
		140	it into the ready queue before scheduling:
		141
		142	# this is exactly what Coro::cede does
		143	$Coro::current->ready;
		144	Coro::schedule;
		145
		146	All the higher-level synchronisation methods (Coro::Semaphore,
		147	Coro::rouse_*...) are actually implemented via "->ready" and
		148	"Coro::schedule".
		149
		150	While the coro thread is running it also might get assigned a
		151	C-level thread, or the C-level thread might be unassigned from it,
		152	as the Coro runtime wishes. A C-level thread needs to be assigned
		153	when your perl thread calls into some C-level function and that
		154	function in turn calls perl and perl then wants to switch
		155	coroutines. This happens most often when you run an event loop and
		156	block in the callback, or when perl itself calls some function such
		157	as "AUTOLOAD" or methods via the "tie" mechanism.
		158
		159	4. Termination
		160	Many threads actually terminate after some time. There are a number
		161	of ways to terminate a coro thread, the simplest is returning from
		162	the top-level code reference:
		163
		164	async {
		165	# after returning from here, the coro thread is terminated
		166	};
		167
		168	async {
		169	return if 0.5 < rand; # terminate a little earlier, maybe
		170	print "got a chance to print this\n";
		171	# or here
		172	};
		173
		174	Any values returned from the coroutine can be recovered using
		175	"->join":
		176
		177	my $coro = async {
		178	"hello, world\n" # return a string
		179	};
		180
		181	my $hello_world = $coro->join;
		182
		183	print $hello_world;
		184
		185	Another way to terminate is to call "Coro::terminate", which at any
		186	subroutine call nesting level:
		187
		188	async {
		189	Coro::terminate "return value 1", "return value 2";
		190	};
		191
		192	And yet another way is to "->cancel" the coro thread from another
		193	thread:
		194
		195	my $coro = async {
		196	exit 1;
		197	};
		198
		199	$coro->cancel; # an also accept values for ->join to retrieve
		200
		201	Cancellation can be dangerous - it's a bit like calling "exit"
		202	without actually exiting, and might leave C libraries and XS modules
		203	in a weird state. Unlike other thread implementations, however, Coro
		204	is exceptionally safe with regards to cancellation, as perl will
		205	always be in a consistent state.
		206
		207	So, cancelling a thread that runs in an XS event loop might not be
		208	the best idea, but any other combination that deals with perl only
		209	(cancelling when a thread is in a "tie" method or an "AUTOLOAD" for
		210	example) is safe.
		211
		212	5. Cleanup
		213	Threads will allocate various resources. Most but not all will be
		214	returned when a thread terminates, during clean-up.
		215
		216	Cleanup is quite similar to throwing an uncaught exception: perl
		217	will work it's way up through all subroutine calls and blocks. On
		218	it's way, it will release all "my" variables, undo all "local"'s and
		219	free any other resources truly local to the thread.
		220
		221	So, a common way to free resources is to keep them referenced only
		222	by my variables:
		223
		224	async {
		225	my $big_cache = new Cache ...;
		226	};
		227
		228	If there are no other references, then the $big_cache object will be
		229	freed when the thread terminates, regardless of how it does so.
		230
		231	What it does "NOT" do is unlock any Coro::Semaphores or similar
		232	resources, but that's where the "guard" methods come in handy:
		233
		234	my $sem = new Coro::Semaphore;
		235
		236	async {
		237	my $lock_guard = $sem->guard;
		238	# if we reutrn, or die or get cancelled, here,
		239	# then the semaphore will be "up"ed.
		240	};
		241
		242	The "Guard::guard" function comes in handy for any custom cleanup
		243	you might want to do:
		244
		245	async {
		246	my $window = new Gtk2::Window "toplevel";
		247	# The window will not be cleaned up automatically, even when $window
		248	# gets freed, so use a guard to ensure it's destruction
		249	# in case of an error:
		250	my $window_guard = Guard::guard { $window->destroy };
		251
		252	# we are safe here
		253	};
		254
		255	Last not least, "local" can often be handy, too, e.g. when
		256	temporarily replacing the coro thread description:
		257
		258	sub myfunction {
		259	local $Coro::current->{desc} = "inside myfunction(@_)";
		260
		261	# if we return or die here, the description will be restored
		262	}
		263
		264	6. Viva La Zombie Muerte
		265	Even after a thread has terminated and cleaned up it's resources,
		266	the coro object still is there and stores the return values of the
		267	thread. Only in this state will the coro object be "reference
		268	counted" in the normal perl sense: the thread code keeps a reference
		269	to it when it is active, but not after it has terminated.
		270
		271	The means the coro object gets freed automatically when the thread
		272	has terminated and cleaned up and there arenot other references.
		273
		274	If there are, the coro object will stay around, and you can call
		275	"->join" as many times as you wish to retrieve the result values:
		276
		277	async {
		278	print "hi\n";
		279	1
		280	};
		281
		282	# run the async above, and free everything before returning
		283	# from Coro::cede:
		284	Coro::cede;
		285
		286	{
		287	my $coro = async {
		288	print "hi\n";
		289	1
		290	};
		291
		292	# run the async above, and clean up, but do not free the coro
		293	# object:
		294	Coro::cede;
		295
		296	# optionally retrieve the result values
		297	my @results = $coro->join;
		298
		299	# now $coro goes out of scope, and presumably gets freed
		300	};
66		301
67	GLOBAL VARIABLES	302	GLOBAL VARIABLES
68	$Coro::main	303	$Coro::main
69	This variable stores the Coro object that represents the main	304	This variable stores the Coro object that represents the main
70	program. While you cna "ready" it and do most other things you can	305	program. While you cna "ready" it and do most other things you can
…		…
92	The default implementation dies with "FATAL: deadlock detected.",	327	The default implementation dies with "FATAL: deadlock detected.",
93	followed by a thread listing, because the program has no other way	328	followed by a thread listing, because the program has no other way
94	to continue.	329	to continue.
95		330
96	This hook is overwritten by modules such as "Coro::EV" and	331	This hook is overwritten by modules such as "Coro::EV" and
97	"Coro::AnyEvent" to wait on an external event that hopefully wake up	332	"Coro::AnyEvent" to wait on an external event that hopefully wakes
98	a coro so the scheduler can run it.	333	up a coro so the scheduler can run it.
99		334
100	See Coro::EV or Coro::AnyEvent for examples of using this technique.	335	See Coro::EV or Coro::AnyEvent for examples of using this technique.
101		336
102	SIMPLE CORO CREATION	337	SIMPLE CORO CREATION
103	async { ... } [@args...]	338	async { ... } [@args...]
…		…
411	"terminate" or "cancel" functions. "join" can be called concurrently	646	"terminate" or "cancel" functions. "join" can be called concurrently
412	from multiple coro, and all will be resumed and given the status	647	from multiple coro, and all will be resumed and given the status
413	return once the $coro terminates.	648	return once the $coro terminates.
414		649
415	$coro->on_destroy (\&cb)	650	$coro->on_destroy (\&cb)
416	Registers a callback that is called when this coro gets destroyed,	651	Registers a callback that is called when this coro thread gets
417	but before it is joined. The callback gets passed the terminate	652	destroyed, but before it is joined. The callback gets passed the
418	arguments, if any, and must not die, under any circumstances.	653	terminate arguments, if any, and must not die, under any
		654	circumstances.
		655
		656	There can be any number of "on_destroy" callbacks per coro.
419		657
420	$oldprio = $coro->prio ($newprio)	658	$oldprio = $coro->prio ($newprio)
421	Sets (or gets, if the argument is missing) the priority of the coro.	659	Sets (or gets, if the argument is missing) the priority of the coro
422	Higher priority coro get run before lower priority coro. Priorities	660	thread. Higher priority coro get run before lower priority coros.
423	are small signed integers (currently -4 .. +3), that you can refer	661	Priorities are small signed integers (currently -4 .. +3), that you
424	to using PRIO_xxx constants (use the import tag :prio to get then):	662	can refer to using PRIO_xxx constants (use the import tag :prio to
		663	get then):
425		664
426	PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN	665	PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
427	3 > 1 > 0 > -1 > -3 > -4	666	3 > 1 > 0 > -1 > -3 > -4
428		667
429	# set priority to HIGH	668	# set priority to HIGH
430	current->prio (PRIO_HIGH);	669	current->prio (PRIO_HIGH);
431		670
432	The idle coro ($Coro::idle) always has a lower priority than any	671	The idle coro thread ($Coro::idle) always has a lower priority than
433	existing coro.	672	any existing coro.
434		673
435	Changing the priority of the current coro will take effect	674	Changing the priority of the current coro will take effect
436	immediately, but changing the priority of coro in the ready queue	675	immediately, but changing the priority of a coro in the ready queue
437	(but not running) will only take effect after the next schedule (of	676	(but not running) will only take effect after the next schedule (of
438	that coro). This is a bug that will be fixed in some future version.	677	that coro). This is a bug that will be fixed in some future version.
439		678
440	$newprio = $coro->nice ($change)	679	$newprio = $coro->nice ($change)
441	Similar to "prio", but subtract the given value from the priority	680	Similar to "prio", but subtract the given value from the priority
442	(i.e. higher values mean lower priority, just as in unix).	681	(i.e. higher values mean lower priority, just as in UNIX's nice
		682	command).
443		683
444	$olddesc = $coro->desc ($newdesc)	684	$olddesc = $coro->desc ($newdesc)
445	Sets (or gets in case the argument is missing) the description for	685	Sets (or gets in case the argument is missing) the description for
446	this coro. This is just a free-form string you can associate with a	686	this coro thread. This is just a free-form string you can associate
447	coro.	687	with a coro.
448		688
449	This method simply sets the "$coro->{desc}" member to the given	689	This method simply sets the "$coro->{desc}" member to the given
450	string. You can modify this member directly if you wish.	690	string. You can modify this member directly if you wish, and in
		691	fact, this is often preferred to indicate major processing states
		692	that cna then be seen for example in a Coro::Debug session:
		693
		694	sub my_long_function {
		695	local $Coro::current->{desc} = "now in my_long_function";
		696	...
		697	$Coro::current->{desc} = "my_long_function: phase 1";
		698	...
		699	$Coro::current->{desc} = "my_long_function: phase 2";
		700	...
		701	}
451		702
452	GLOBAL FUNCTIONS	703	GLOBAL FUNCTIONS
453	Coro::nready	704	Coro::nready
454	Returns the number of coro that are currently in the ready state,	705	Returns the number of coro that are currently in the ready state,
455	i.e. that can be switched to by calling "schedule" directory or	706	i.e. that can be switched to by calling "schedule" directory or
…		…
472	The reason this function exists is that many event libraries (such	723	The reason this function exists is that many event libraries (such
473	as the venerable Event module) are not thread-safe (a weaker form of	724	as the venerable Event module) are not thread-safe (a weaker form of
474	reentrancy). This means you must not block within event callbacks,	725	reentrancy). This means you must not block within event callbacks,
475	otherwise you might suffer from crashes or worse. The only event	726	otherwise you might suffer from crashes or worse. The only event
476	library currently known that is safe to use without "unblock_sub" is	727	library currently known that is safe to use without "unblock_sub" is
477	EV.	728	EV (but you might still run into deadlocks if all event loops are
		729	blocked).
478		730
479	Coro will try to catch you when you block in the event loop	731	Coro will try to catch you when you block in the event loop
480	("FATAL:$Coro::IDLE blocked itself"), but this is just best effort	732	("FATAL:$Coro::IDLE blocked itself"), but this is just best effort
481	and only works when you do not run your own event loop.	733	and only works when you do not run your own event loop.
482		734
…		…
616	ithreads (for example, that memory or files would be shared), showing	868	ithreads (for example, that memory or files would be shared), showing
617	his lack of understanding of this area - if it is hard to understand for	869	his lack of understanding of this area - if it is hard to understand for
618	Chip, it is probably not obvious to everybody).	870	Chip, it is probably not obvious to everybody).
619		871
620	What follows is an ultra-condensed version of my talk about threads in	872	What follows is an ultra-condensed version of my talk about threads in
621	scripting languages given onthe perl workshop 2009:	873	scripting languages given on the perl workshop 2009:
622		874
623	The so-called "ithreads" were originally implemented for two reasons:	875	The so-called "ithreads" were originally implemented for two reasons:
624	first, to (badly) emulate unix processes on native win32 perls, and	876	first, to (badly) emulate unix processes on native win32 perls, and
625	secondly, to replace the older, real thread model ("5.005-threads").	877	secondly, to replace the older, real thread model ("5.005-threads").
626		878

Diff Legend

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

Comparing Coro/README (file contents): Revision 1.27 by root, Fri Dec 25 07:17:12 2009 UTC vs. Revision 1.29 by root, Sat Feb 19 06:51:22 2011 UTC

Diff Legend

Comparing Coro/README (file contents):
Revision 1.27 by root, Fri Dec 25 07:17:12 2009 UTC vs.
Revision 1.29 by root, Sat Feb 19 06:51:22 2011 UTC