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

Comparing Coro/Coro.pm (file contents):
Revision 1.251 by root, Mon Mar 16 22:22:12 2009 UTC vs.
Revision 1.270 by root, Thu Oct 1 23:50:23 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, and as such act	45	but only the windows process emulation (see section of same name for more
46	as processes), Coro provides a full shared address space, which makes	46	details) ported to unix, and as such act as processes), Coro provides
47	communication between threads very easy. And Coro's threads are fast,	47	a full shared address space, which makes communication between threads
48	too: disabling the Windows process emulation code in your perl and using	48	very easy. And Coro's threads are fast, too: disabling the Windows
49	Coro can easily result in a two to four times speed increase for your	49	process emulation code in your perl and using Coro can easily result in
50	programs. A parallel matrix multiplication benchmark runs over 300 times	50	a two to four times speed increase for your programs. A parallel matrix
51	faster on a single core than perl's pseudo-threads on a quad core using	51	multiplication benchmark runs over 300 times faster on a single core than
52	all four cores.	52	perl's pseudo-threads on a quad core using all four cores.
53		53
54	Coro achieves that by supporting multiple running interpreters that share	54	Coro achieves that by supporting multiple running interpreters that share
55	data, which is especially useful to code pseudo-parallel processes and	55	data, which is especially useful to code pseudo-parallel processes and
56	for event-based programming, such as multiple HTTP-GET requests running	56	for event-based programming, such as multiple HTTP-GET requests running
57	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
…		…
67		67
68	=cut	68	=cut
69		69
70	package Coro;	70	package Coro;
71		71
72	use strict qw(vars subs);	72	use common::sense;
73	no warnings "uninitialized";	73
		74	use Carp ();
74		75
75	use Guard ();	76	use Guard ();
76		77
77	use Coro::State;	78	use Coro::State;
78		79
…		…
80		81
81	our $idle; # idle handler	82	our $idle; # idle handler
82	our $main; # main coro	83	our $main; # main coro
83	our $current; # current coro	84	our $current; # current coro
84		85
85	our $VERSION = 5.131;	86	our $VERSION = 5.17;
86		87
87	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);
88	our %EXPORT_TAGS = (	89	our %EXPORT_TAGS = (
89	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)],
90	);	91	);
…		…
123		124
124	This variable is mainly useful to integrate Coro into event loops. It is	125	This variable is mainly useful to integrate Coro into event loops. It is
125	usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is	126	usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is
126	pretty low-level functionality.	127	pretty low-level functionality.
127		128
128	This variable stores either a Coro object or a callback.	129	This variable stores a Coro object that is put into the ready queue when
		130	there are no other ready threads (without invoking any ready hooks).
129		131
130	If it is a callback, the it is called whenever the scheduler finds no	132	The default implementation dies with "FATAL: deadlock detected.", followed
131	ready coros to run. The default implementation prints "FATAL:	133	by a thread listing, because the program has no other way to continue.
132	deadlock detected" and exits, because the program has no other way to
133	continue.
134
135	If it is a coro object, then this object will be readied (without
136	invoking any ready hooks, however) when the scheduler finds no other ready
137	coros to run.
138		134
139	This hook is overwritten by modules such as C<Coro::EV> and	135	This hook is overwritten by modules such as C<Coro::EV> and
140	C<Coro::AnyEvent> to wait on an external event that hopefully wake up a	136	C<Coro::AnyEvent> to wait on an external event that hopefully wake up a
141	coro so the scheduler can run it.	137	coro so the scheduler can run it.
142		138
143	Note that the callback I<must not>, under any circumstances, block
144	the current coro. Normally, this is achieved by having an "idle
145	coro" that calls the event loop and then blocks again, and then
146	readying that coro in the idle handler, or by simply placing the idle
147	coro in this variable.
148
149	See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this	139	See L<Coro::EV> or L<Coro::AnyEvent> for examples of using this technique.
150	technique.
151		140
152	Please note that if your callback recursively invokes perl (e.g. for event
153	handlers), then it must be prepared to be called recursively itself.
154
155	=cut	141	=cut
156		142
157	$idle = sub {	143	$idle = new Coro sub {
158	require Carp;	144	require Coro::Debug;
159	Carp::croak ("FATAL: deadlock detected");	145	die "FATAL: deadlock detected.\n"
		146	. Coro::Debug::ps_listing ();
160	};	147	};
161		148
162	# this coro is necessary because a coro	149	# this coro is necessary because a coro
163	# cannot destroy itself.	150	# cannot destroy itself.
164	our @destroy;	151	our @destroy;
…		…
206	Example: Create a new coro that just prints its arguments.	193	Example: Create a new coro that just prints its arguments.
207		194
208	async {	195	async {
209	print "@_\n";	196	print "@_\n";
210	} 1,2,3,4;	197	} 1,2,3,4;
211
212	=cut
213
214	sub async(&@) {
215	my $coro = new Coro @_;
216	$coro->ready;
217	$coro
218	}
219		198
220	=item async_pool { ... } [@args...]	199	=item async_pool { ... } [@args...]
221		200
222	Similar to C<async>, but uses a coro pool, so you should not call	201	Similar to C<async>, but uses a coro pool, so you should not call
223	terminate or join on it (although you are allowed to), and you get a	202	terminate or join on it (although you are allowed to), and you get a
…		…
280	=item schedule	259	=item schedule
281		260
282	Calls the scheduler. The scheduler will find the next coro that is	261	Calls the scheduler. The scheduler will find the next coro that is
283	to be run from the ready queue and switches to it. The next coro	262	to be run from the ready queue and switches to it. The next coro
284	to be run is simply the one with the highest priority that is longest	263	to be run is simply the one with the highest priority that is longest
285	in its ready queue. If there is no coro ready, it will clal the	264	in its ready queue. If there is no coro ready, it will call the
286	C<$Coro::idle> hook.	265	C<$Coro::idle> hook.
287		266
288	Please note that the current coro will I<not> be put into the ready	267	Please note that the current coro will I<not> be put into the ready
289	queue, so calling this function usually means you will never be called	268	queue, so calling this function usually means you will never be called
290	again unless something else (e.g. an event handler) calls C<< ->ready >>,	269	again unless something else (e.g. an event handler) calls C<< ->ready >>,
…		…
338		317
339	These functions implement the same concept as C<dynamic-wind> in scheme	318	These functions implement the same concept as C<dynamic-wind> in scheme
340	does, and are useful when you want to localise some resource to a specific	319	does, and are useful when you want to localise some resource to a specific
341	coro.	320	coro.
342		321
343	They slow down coro switching considerably for coros that use	322	They slow down thread switching considerably for coros that use them
344	them (But coro switching is still reasonably fast if the handlers are	323	(about 40% for a BLOCK with a single assignment, so thread switching is
345	fast).	324	still reasonably fast if the handlers are fast).
346		325
347	These functions are best understood by an example: The following function	326	These functions are best understood by an example: The following function
348	will change the current timezone to "Antarctica/South_Pole", which	327	will change the current timezone to "Antarctica/South_Pole", which
349	requires a call to C<tzset>, but by using C<on_enter> and C<on_leave>,	328	requires a call to C<tzset>, but by using C<on_enter> and C<on_leave>,
350	which remember/change the current timezone and restore the previous	329	which remember/change the current timezone and restore the previous
351	value, respectively, the timezone is only changes for the coro that	330	value, respectively, the timezone is only changed for the coro that
352	installed those handlers.	331	installed those handlers.
353		332
354	use POSIX qw(tzset);	333	use POSIX qw(tzset);
355		334
356	async {	335	async {
…		…
373	};	352	};
374		353
375	This can be used to localise about any resource (locale, uid, current	354	This can be used to localise about any resource (locale, uid, current
376	working directory etc.) to a block, despite the existance of other	355	working directory etc.) to a block, despite the existance of other
377	coros.	356	coros.
		357
		358	Another interesting example implements time-sliced multitasking using
		359	interval timers (this could obviously be optimised, but does the job):
		360
		361	# "timeslice" the given block
		362	sub timeslice(&) {
		363	use Time::HiRes ();
		364
		365	Coro::on_enter {
		366	# on entering the thread, we set an VTALRM handler to cede
		367	$SIG{VTALRM} = sub { cede };
		368	# and then start the interval timer
		369	Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01;
		370	};
		371	Coro::on_leave {
		372	# on leaving the thread, we stop the interval timer again
		373	Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0;
		374	};
		375
		376	&{+shift};
		377	}
		378
		379	# use like this:
		380	timeslice {
		381	# The following is an endless loop that would normally
		382	# monopolise the process. Since it runs in a timesliced
		383	# environment, it will regularly cede to other threads.
		384	while () { }
		385	};
		386
378		387
379	=item killall	388	=item killall
380		389
381	Kills/terminates/cancels all coros except the currently running one.	390	Kills/terminates/cancels all coros except the currently running one.
382		391
…		…
721	Wait for the specified rouse callback (or the last one that was created in	730	Wait for the specified rouse callback (or the last one that was created in
722	this coro).	731	this coro).
723		732
724	As soon as the callback is invoked (or when the callback was invoked	733	As soon as the callback is invoked (or when the callback was invoked
725	before C<rouse_wait>), it will return the arguments originally passed to	734	before C<rouse_wait>), it will return the arguments originally passed to
726	the rouse callback.	735	the rouse callback. In scalar context, that means you get the I<last>
		736	argument, just as if C<rouse_wait> had a C<return ($a1, $a2, $a3...)>
		737	statement at the end.
727		738
728	See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.	739	See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
729		740
730	=back	741	=back
731		742
…		…
830	works.	841	works.
831		842
832	=back	843	=back
833		844
834		845
		846	=head1 WINDOWS PROCESS EMULATION
		847
		848	A great many people seem to be confused about ithreads (for example, Chip
		849	Salzenberg called me unintelligent, incapable, stupid and gullible,
		850	while in the same mail making rather confused statements about perl
		851	ithreads (for example, that memory or files would be shared), showing his
		852	lack of understanding of this area - if it is hard to understand for Chip,
		853	it is probably not obvious to everybody).
		854
		855	What follows is an ultra-condensed version of my talk about threads in
		856	scripting languages given onthe perl workshop 2009:
		857
		858	The so-called "ithreads" were originally implemented for two reasons:
		859	first, to (badly) emulate unix processes on native win32 perls, and
		860	secondly, to replace the older, real thread model ("5.005-threads").
		861
		862	It does that by using threads instead of OS processes. The difference
		863	between processes and threads is that threads share memory (and other
		864	state, such as files) between threads within a single process, while
		865	processes do not share anything (at least not semantically). That
		866	means that modifications done by one thread are seen by others, while
		867	modifications by one process are not seen by other processes.
		868
		869	The "ithreads" work exactly like that: when creating a new ithreads
		870	process, all state is copied (memory is copied physically, files and code
		871	is copied logically). Afterwards, it isolates all modifications. On UNIX,
		872	the same behaviour can be achieved by using operating system processes,
		873	except that UNIX typically uses hardware built into the system to do this
		874	efficiently, while the windows process emulation emulates this hardware in
		875	software (rather efficiently, but of course it is still much slower than
		876	dedicated hardware).
		877
		878	As mentioned before, loading code, modifying code, modifying data
		879	structures and so on is only visible in the ithreads process doing the
		880	modification, not in other ithread processes within the same OS process.
		881
		882	This is why "ithreads" do not implement threads for perl at all, only
		883	processes. What makes it so bad is that on non-windows platforms, you can
		884	actually take advantage of custom hardware for this purpose (as evidenced
		885	by the forks module, which gives you the (i-) threads API, just much
		886	faster).
		887
		888	Sharing data is in the i-threads model is done by transfering data
		889	structures between threads using copying semantics, which is very slow -
		890	shared data simply does not exist. Benchmarks using i-threads which are
		891	communication-intensive show extremely bad behaviour with i-threads (in
		892	fact, so bad that Coro, which cannot take direct advantage of multiple
		893	CPUs, is often orders of magnitude faster because it shares data using
		894	real threads, refer to my talk for details).
		895
		896	As summary, i-threads use threads to implement processes, while
		897	the compatible forks module uses processes to emulate, uhm,
		898	processes. I-threads slow down every perl program when enabled, and
		899	outside of windows, serve no (or little) practical purpose, but
		900	disadvantages every single-threaded Perl program.
		901
		902	This is the reason that I try to avoid the name "ithreads", as it is
		903	misleading as it implies that it implements some kind of thread model for
		904	perl, and prefer the name "windows process emulation", which describes the
		905	actual use and behaviour of it much better.
		906
835	=head1 SEE ALSO	907	=head1 SEE ALSO
836		908
837	Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.	909	Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.
838		910
839	Debugging: L<Coro::Debug>.	911	Debugging: L<Coro::Debug>.

Diff Legend

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

Comparing Coro/Coro.pm (file contents): Revision 1.251 by root, Mon Mar 16 22:22:12 2009 UTC vs. Revision 1.270 by root, Thu Oct 1 23:50:23 2009 UTC

Diff Legend

Comparing Coro/Coro.pm (file contents):
Revision 1.251 by root, Mon Mar 16 22:22:12 2009 UTC vs.
Revision 1.270 by root, Thu Oct 1 23:50:23 2009 UTC