[ViewVC] Diff of: cvs/Coro/Coro.pm

Comparing Coro/Coro.pm (file contents):
Revision 1.248 by root, Mon Dec 15 15:03:31 2008 UTC vs.
Revision 1.268 by root, Thu Oct 1 23:16:27 2009 UTC

…		…
40	points in your program, so locking and parallel access are rarely an	40	points in your program, so locking and parallel access are rarely an
41	issue, making thread programming much safer and easier than using other	41	issue, making thread programming much safer and easier than using other
42	thread models.	42	thread models.
43		43
44	Unlike the so-called "Perl threads" (which are not actually real threads	44	Unlike the so-called "Perl threads" (which are not actually real threads
45	but only the windows process emulation ported to unix), Coro provides a	45	but only the windows process emulation (see section of same name for more
		46	details) ported to unix, and as such act as processes), Coro provides
46	full shared address space, which makes communication between threads	47	a full shared address space, which makes communication between threads
47	very easy. And threads are fast, too: disabling the Windows process	48	very easy. And Coro's threads are fast, too: disabling the Windows
48	emulation code in your perl and using Coro can easily result in a two to	49	process emulation code in your perl and using Coro can easily result in
49	four times speed increase for your programs.	50	a two to four times speed increase for your programs. A parallel matrix
		51	multiplication benchmark runs over 300 times faster on a single core than
		52	perl's pseudo-threads on a quad core using all four cores.
50		53
51	Coro achieves that by supporting multiple running interpreters that share	54	Coro achieves that by supporting multiple running interpreters that share
52	data, which is especially useful to code pseudo-parallel processes and	55	data, which is especially useful to code pseudo-parallel processes and
53	for event-based programming, such as multiple HTTP-GET requests running	56	for event-based programming, such as multiple HTTP-GET requests running
54	concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro	57	concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro
55	into an event-based environment.	58	into an event-based environment.
56		59
57	In this module, a thread is defined as "callchain + lexical variables +	60	In this module, a thread is defined as "callchain + lexical variables +
58	@_ + $_ + $@ + $/ + C stack), that is, a thread has its own callchain,	61	some package variables + C stack), that is, a thread has its own callchain,
59	its own set of lexicals and its own set of perls most important global	62	its own set of lexicals and its own set of perls most important global
60	variables (see L<Coro::State> for more configuration and background info).	63	variables (see L<Coro::State> for more configuration and background info).
61		64
62	See also the C<SEE ALSO> section at the end of this document - the Coro	65	See also the C<SEE ALSO> section at the end of this document - the Coro
63	module family is quite large.	66	module family is quite large.
64		67
65	=cut	68	=cut
66		69
67	package Coro;	70	package Coro;
68		71
69	use strict qw(vars subs);	72	use common::sense;
70	no warnings "uninitialized";	73
		74	use Carp ();
71		75
72	use Guard ();	76	use Guard ();
73		77
74	use Coro::State;	78	use Coro::State;
75		79
…		…
77		81
78	our $idle; # idle handler	82	our $idle; # idle handler
79	our $main; # main coro	83	our $main; # main coro
80	our $current; # current coro	84	our $current; # current coro
81		85
82	our $VERSION = 5.13;	86	our $VERSION = 5.17;
83		87
84	our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);	88	our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
85	our %EXPORT_TAGS = (	89	our %EXPORT_TAGS = (
86	prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],	90	prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
87	);	91	);
…		…
150	handlers), then it must be prepared to be called recursively itself.	154	handlers), then it must be prepared to be called recursively itself.
151		155
152	=cut	156	=cut
153		157
154	$idle = sub {	158	$idle = sub {
155	require Carp;	159	warn "oi\n";#d#
156	Carp::croak ("FATAL: deadlock detected");	160	Carp::confess ("FATAL: deadlock detected");
157	};	161	};
158		162
159	# this coro is necessary because a coro	163	# this coro is necessary because a coro
160	# cannot destroy itself.	164	# cannot destroy itself.
161	our @destroy;	165	our @destroy;
…		…
203	Example: Create a new coro that just prints its arguments.	207	Example: Create a new coro that just prints its arguments.
204		208
205	async {	209	async {
206	print "@_\n";	210	print "@_\n";
207	} 1,2,3,4;	211	} 1,2,3,4;
208
209	=cut
210
211	sub async(&@) {
212	my $coro = new Coro @_;
213	$coro->ready;
214	$coro
215	}
216		212
217	=item async_pool { ... } [@args...]	213	=item async_pool { ... } [@args...]
218		214
219	Similar to C<async>, but uses a coro pool, so you should not call	215	Similar to C<async>, but uses a coro pool, so you should not call
220	terminate or join on it (although you are allowed to), and you get a	216	terminate or join on it (although you are allowed to), and you get a
…		…
335		331
336	These functions implement the same concept as C<dynamic-wind> in scheme	332	These functions implement the same concept as C<dynamic-wind> in scheme
337	does, and are useful when you want to localise some resource to a specific	333	does, and are useful when you want to localise some resource to a specific
338	coro.	334	coro.
339		335
340	They slow down coro switching considerably for coros that use	336	They slow down thread switching considerably for coros that use them
341	them (But coro switching is still reasonably fast if the handlers are	337	(about 40% for a BLOCK with a single assignment, so thread switching is
342	fast).	338	still reasonably fast if the handlers are fast).
343		339
344	These functions are best understood by an example: The following function	340	These functions are best understood by an example: The following function
345	will change the current timezone to "Antarctica/South_Pole", which	341	will change the current timezone to "Antarctica/South_Pole", which
346	requires a call to C<tzset>, but by using C<on_enter> and C<on_leave>,	342	requires a call to C<tzset>, but by using C<on_enter> and C<on_leave>,
347	which remember/change the current timezone and restore the previous	343	which remember/change the current timezone and restore the previous
348	value, respectively, the timezone is only changes for the coro that	344	value, respectively, the timezone is only changed for the coro that
349	installed those handlers.	345	installed those handlers.
350		346
351	use POSIX qw(tzset);	347	use POSIX qw(tzset);
352		348
353	async {	349	async {
…		…
370	};	366	};
371		367
372	This can be used to localise about any resource (locale, uid, current	368	This can be used to localise about any resource (locale, uid, current
373	working directory etc.) to a block, despite the existance of other	369	working directory etc.) to a block, despite the existance of other
374	coros.	370	coros.
		371
		372	Another interesting example implements time-sliced multitasking using
		373	interval timers (this could obviously be optimised, but does the job):
		374
		375	# "timeslice" the given block
		376	sub timeslice(&) {
		377	use Time::HiRes ();
		378
		379	Coro::on_enter {
		380	# on entering the thread, we set an VTALRM handler to cede
		381	$SIG{VTALRM} = sub { cede };
		382	# and then start the interval timer
		383	Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01;
		384	};
		385	Coro::on_leave {
		386	# on leaving the thread, we stop the interval timer again
		387	Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0;
		388	};
		389
		390	&{+shift};
		391	}
		392
		393	# use like this:
		394	timeslice {
		395	# The following is an endless loop that would normally
		396	# monopolise the process. Since it runs in a timesliced
		397	# environment, it will regularly cede to other threads.
		398	while () { }
		399	};
		400
375		401
376	=item killall	402	=item killall
377		403
378	Kills/terminates/cancels all coros except the currently running one.	404	Kills/terminates/cancels all coros except the currently running one.
379		405
…		…
423	the ready queue, do nothing and return false.	449	the ready queue, do nothing and return false.
424		450
425	This ensures that the scheduler will resume this coro automatically	451	This ensures that the scheduler will resume this coro automatically
426	once all the coro of higher priority and all coro of the same	452	once all the coro of higher priority and all coro of the same
427	priority that were put into the ready queue earlier have been resumed.	453	priority that were put into the ready queue earlier have been resumed.
		454
		455	=item $coro->suspend
		456
		457	Suspends the specified coro. A suspended coro works just like any other
		458	coro, except that the scheduler will not select a suspended coro for
		459	execution.
		460
		461	Suspending a coro can be useful when you want to keep the coro from
		462	running, but you don't want to destroy it, or when you want to temporarily
		463	freeze a coro (e.g. for debugging) to resume it later.
		464
		465	A scenario for the former would be to suspend all (other) coros after a
		466	fork and keep them alive, so their destructors aren't called, but new
		467	coros can be created.
		468
		469	=item $coro->resume
		470
		471	If the specified coro was suspended, it will be resumed. Note that when
		472	the coro was in the ready queue when it was suspended, it might have been
		473	unreadied by the scheduler, so an activation might have been lost.
		474
		475	To avoid this, it is best to put a suspended coro into the ready queue
		476	unconditionally, as every synchronisation mechanism must protect itself
		477	against spurious wakeups, and the one in the Coro family certainly do
		478	that.
428		479
429	=item $is_ready = $coro->is_ready	480	=item $is_ready = $coro->is_ready
430		481
431	Returns true iff the Coro object is in the ready queue. Unless the Coro	482	Returns true iff the Coro object is in the ready queue. Unless the Coro
432	object gets destroyed, it will eventually be scheduled by the scheduler.	483	object gets destroyed, it will eventually be scheduled by the scheduler.
…		…
693	Wait for the specified rouse callback (or the last one that was created in	744	Wait for the specified rouse callback (or the last one that was created in
694	this coro).	745	this coro).
695		746
696	As soon as the callback is invoked (or when the callback was invoked	747	As soon as the callback is invoked (or when the callback was invoked
697	before C<rouse_wait>), it will return the arguments originally passed to	748	before C<rouse_wait>), it will return the arguments originally passed to
698	the rouse callback.	749	the rouse callback. In scalar context, that means you get the I<last>
		750	argument, just as if C<rouse_wait> had a C<return ($a1, $a2, $a3...)>
		751	statement at the end.
699		752
700	See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.	753	See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
701		754
702	=back	755	=back
703		756
…		…
802	works.	855	works.
803		856
804	=back	857	=back
805		858
806		859
		860	=head1 WINDOWS PROCESS EMULATION
		861
		862	A great many people seem to be confused about ithreads (for example, Chip
		863	Salzenberg called me unintelligent, incapable, stupid and gullible,
		864	while in the same mail making rather confused statements about perl
		865	ithreads (for example, that memory or files would be shared), showing his
		866	lack of understanding of this area - if it is hard to understand for Chip,
		867	it is probably not obvious to everybody).
		868
		869	What follows is an ultra-condensed version of my talk about threads in
		870	scripting languages given onthe perl workshop 2009:
		871
		872	The so-called "ithreads" were originally implemented for two reasons:
		873	first, to (badly) emulate unix processes on native win32 perls, and
		874	secondly, to replace the older, real thread model ("5.005-threads").
		875
		876	It does that by using threads instead of OS processes. The difference
		877	between processes and threads is that threads share memory (and other
		878	state, such as files) between threads within a single process, while
		879	processes do not share anything (at least not semantically). That
		880	means that modifications done by one thread are seen by others, while
		881	modifications by one process are not seen by other processes.
		882
		883	The "ithreads" work exactly like that: when creating a new ithreads
		884	process, all state is copied (memory is copied physically, files and code
		885	is copied logically). Afterwards, it isolates all modifications. On UNIX,
		886	the same behaviour can be achieved by using operating system processes,
		887	except that UNIX typically uses hardware built into the system to do this
		888	efficiently, while the windows process emulation emulates this hardware in
		889	software (rather efficiently, but of course it is still much slower than
		890	dedicated hardware).
		891
		892	As mentioned before, loading code, modifying code, modifying data
		893	structures and so on is only visible in the ithreads process doing the
		894	modification, not in other ithread processes within the same OS process.
		895
		896	This is why "ithreads" do not implement threads for perl at all, only
		897	processes. What makes it so bad is that on non-windows platforms, you can
		898	actually take advantage of custom hardware for this purpose (as evidenced
		899	by the forks module, which gives you the (i-) threads API, just much
		900	faster).
		901
		902	Sharing data is in the i-threads model is done by transfering data
		903	structures between threads using copying semantics, which is very slow -
		904	shared data simply does not exist. Benchmarks using i-threads which are
		905	communication-intensive show extremely bad behaviour with i-threads (in
		906	fact, so bad that Coro, which cannot take direct advantage of multiple
		907	CPUs, is often orders of magnitude faster because it shares data using
		908	real threads, refer to my talk for details).
		909
		910	As summary, i-threads use threads to implement processes, while
		911	the compatible forks module uses processes to emulate, uhm,
		912	processes. I-threads slow down every perl program when enabled, and
		913	outside of windows, serve no (or little) practical purpose, but
		914	disadvantages every single-threaded Perl program.
		915
		916	This is the reason that I try to avoid the name "ithreads", as it is
		917	misleading as it implies that it implements some kind of thread model for
		918	perl, and prefer the name "windows process emulation", which describes the
		919	actual use and behaviour of it much better.
		920
807	=head1 SEE ALSO	921	=head1 SEE ALSO
808		922
809	Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.	923	Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.
810		924
811	Debugging: L<Coro::Debug>.	925	Debugging: L<Coro::Debug>.

Diff Legend

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

Comparing Coro/Coro.pm (file contents): Revision 1.248 by root, Mon Dec 15 15:03:31 2008 UTC vs. Revision 1.268 by root, Thu Oct 1 23:16:27 2009 UTC

Diff Legend

Comparing Coro/Coro.pm (file contents):
Revision 1.248 by root, Mon Dec 15 15:03:31 2008 UTC vs.
Revision 1.268 by root, Thu Oct 1 23:16:27 2009 UTC