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

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.248 by root, Mon Dec 15 15:03:31 2008 UTC vs.
Revision 1.274 by root, Sat Dec 12 01:30:26 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.21;
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 rouse_cb rouse_wait);
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	);
88	our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));	92	our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
89		93
…		…
120		124
121	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
122	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
123	pretty low-level functionality.	127	pretty low-level functionality.
124		128
125	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).
126		131
127	If it is a callback, the it is called whenever the scheduler finds no	132	The default implementation dies with "FATAL: deadlock detected.", followed
128	ready coros to run. The default implementation prints "FATAL:	133	by a thread listing, because the program has no other way to continue.
129	deadlock detected" and exits, because the program has no other way to
130	continue.
131
132	If it is a coro object, then this object will be readied (without
133	invoking any ready hooks, however) when the scheduler finds no other ready
134	coros to run.
135		134
136	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
137	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
138	coro so the scheduler can run it.	137	coro so the scheduler can run it.
139		138
140	Note that the callback I<must not>, under any circumstances, block
141	the current coro. Normally, this is achieved by having an "idle
142	coro" that calls the event loop and then blocks again, and then
143	readying that coro in the idle handler, or by simply placing the idle
144	coro in this variable.
145
146	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.
147	technique.
148		140
149	Please note that if your callback recursively invokes perl (e.g. for event
150	handlers), then it must be prepared to be called recursively itself.
151
152	=cut	141	=cut
153		142
154	$idle = sub {	143	$idle = new Coro sub {
155	require Carp;	144	require Coro::Debug;
156	Carp::croak ("FATAL: deadlock detected");	145	die "FATAL: deadlock detected.\n"
		146	. Coro::Debug::ps_listing ();
157	};	147	};
158		148
159	# this coro is necessary because a coro	149	# this coro is necessary because a coro
160	# cannot destroy itself.	150	# cannot destroy itself.
161	our @destroy;	151	our @destroy;
…		…
203	Example: Create a new coro that just prints its arguments.	193	Example: Create a new coro that just prints its arguments.
204		194
205	async {	195	async {
206	print "@_\n";	196	print "@_\n";
207	} 1,2,3,4;	197	} 1,2,3,4;
208
209	=cut
210
211	sub async(&@) {
212	my $coro = new Coro @_;
213	$coro->ready;
214	$coro
215	}
216		198
217	=item async_pool { ... } [@args...]	199	=item async_pool { ... } [@args...]
218		200
219	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
220	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
…		…
277	=item schedule	259	=item schedule
278		260
279	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
280	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
281	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
282	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
283	C<$Coro::idle> hook.	265	C<$Coro::idle> hook.
284		266
285	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
286	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
287	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 >>,
…		…
335		317
336	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
337	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
338	coro.	320	coro.
339		321
340	They slow down coro switching considerably for coros that use	322	They slow down thread switching considerably for coros that use them
341	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
342	fast).	324	still reasonably fast if the handlers are fast).
343		325
344	These functions are best understood by an example: The following function	326	These functions are best understood by an example: The following function
345	will change the current timezone to "Antarctica/South_Pole", which	327	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>,	328	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	329	which remember/change the current timezone and restore the previous
348	value, respectively, the timezone is only changes for the coro that	330	value, respectively, the timezone is only changed for the coro that
349	installed those handlers.	331	installed those handlers.
350		332
351	use POSIX qw(tzset);	333	use POSIX qw(tzset);
352		334
353	async {	335	async {
…		…
370	};	352	};
371		353
372	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
373	working directory etc.) to a block, despite the existance of other	355	working directory etc.) to a block, despite the existance of other
374	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
375		387
376	=item killall	388	=item killall
377		389
378	Kills/terminates/cancels all coros except the currently running one.	390	Kills/terminates/cancels all coros except the currently running one.
379		391
…		…
423	the ready queue, do nothing and return false.	435	the ready queue, do nothing and return false.
424		436
425	This ensures that the scheduler will resume this coro automatically	437	This ensures that the scheduler will resume this coro automatically
426	once all the coro of higher priority and all coro of the same	438	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.	439	priority that were put into the ready queue earlier have been resumed.
		440
		441	=item $coro->suspend
		442
		443	Suspends the specified coro. A suspended coro works just like any other
		444	coro, except that the scheduler will not select a suspended coro for
		445	execution.
		446
		447	Suspending a coro can be useful when you want to keep the coro from
		448	running, but you don't want to destroy it, or when you want to temporarily
		449	freeze a coro (e.g. for debugging) to resume it later.
		450
		451	A scenario for the former would be to suspend all (other) coros after a
		452	fork and keep them alive, so their destructors aren't called, but new
		453	coros can be created.
		454
		455	=item $coro->resume
		456
		457	If the specified coro was suspended, it will be resumed. Note that when
		458	the coro was in the ready queue when it was suspended, it might have been
		459	unreadied by the scheduler, so an activation might have been lost.
		460
		461	To avoid this, it is best to put a suspended coro into the ready queue
		462	unconditionally, as every synchronisation mechanism must protect itself
		463	against spurious wakeups, and the one in the Coro family certainly do
		464	that.
428		465
429	=item $is_ready = $coro->is_ready	466	=item $is_ready = $coro->is_ready
430		467
431	Returns true iff the Coro object is in the ready queue. Unless the Coro	468	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.	469	object gets destroyed, it will eventually be scheduled by the scheduler.
…		…
627	The reason this function exists is that many event libraries (such as the	664	The reason this function exists is that many event libraries (such as the
628	venerable L<Event\|Event> module) are not thread-safe (a weaker form	665	venerable L<Event\|Event> module) are not thread-safe (a weaker form
629	of reentrancy). This means you must not block within event callbacks,	666	of reentrancy). This means you must not block within event callbacks,
630	otherwise you might suffer from crashes or worse. The only event library	667	otherwise you might suffer from crashes or worse. The only event library
631	currently known that is safe to use without C<unblock_sub> is L<EV>.	668	currently known that is safe to use without C<unblock_sub> is L<EV>.
		669
		670	Coro will try to catch you when you block in the event loop
		671	("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and
		672	only works when you do not run your own event loop.
632		673
633	This function allows your callbacks to block by executing them in another	674	This function allows your callbacks to block by executing them in another
634	coro where it is safe to block. One example where blocking is handy	675	coro where it is safe to block. One example where blocking is handy
635	is when you use the L<Coro::AIO\|Coro::AIO> functions to save results to	676	is when you use the L<Coro::AIO\|Coro::AIO> functions to save results to
636	disk, for example.	677	disk, for example.
…		…
678	unshift @unblock_queue, [$cb, @_];	719	unshift @unblock_queue, [$cb, @_];
679	$unblock_scheduler->ready;	720	$unblock_scheduler->ready;
680	}	721	}
681	}	722	}
682		723
683	=item $cb = Coro::rouse_cb	724	=item $cb = rouse_cb
684		725
685	Create and return a "rouse callback". That's a code reference that,	726	Create and return a "rouse callback". That's a code reference that,
686	when called, will remember a copy of its arguments and notify the owner	727	when called, will remember a copy of its arguments and notify the owner
687	coro of the callback.	728	coro of the callback.
688		729
689	See the next function.	730	See the next function.
690		731
691	=item @args = Coro::rouse_wait [$cb]	732	=item @args = rouse_wait [$cb]
692		733
693	Wait for the specified rouse callback (or the last one that was created in	734	Wait for the specified rouse callback (or the last one that was created in
694	this coro).	735	this coro).
695		736
696	As soon as the callback is invoked (or when the callback was invoked	737	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	738	before C<rouse_wait>), it will return the arguments originally passed to
698	the rouse callback.	739	the rouse callback. In scalar context, that means you get the I<last>
		740	argument, just as if C<rouse_wait> had a C<return ($a1, $a2, $a3...)>
		741	statement at the end.
699		742
700	See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.	743	See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
701		744
702	=back	745	=back
703		746
…		…
791	the windows process emulation enabled under unix roughly halves perl	834	the windows process emulation enabled under unix roughly halves perl
792	performance, even when not used.	835	performance, even when not used.
793		836
794	=item coro switching is not signal safe	837	=item coro switching is not signal safe
795		838
796	You must not switch to another coro from within a signal handler	839	You must not switch to another coro from within a signal handler (only
797	(only relevant with %SIG - most event libraries provide safe signals).	840	relevant with %SIG - most event libraries provide safe signals), I<unless>
		841	you are sure you are not interrupting a Coro function.
798		842
799	That means you I<MUST NOT> call any function that might "block" the	843	That means you I<MUST NOT> call any function that might "block" the
800	current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or	844	current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
801	anything that calls those. Everything else, including calling C<ready>,	845	anything that calls those. Everything else, including calling C<ready>,
802	works.	846	works.
803		847
804	=back	848	=back
805		849
806		850
		851	=head1 WINDOWS PROCESS EMULATION
		852
		853	A great many people seem to be confused about ithreads (for example, Chip
		854	Salzenberg called me unintelligent, incapable, stupid and gullible,
		855	while in the same mail making rather confused statements about perl
		856	ithreads (for example, that memory or files would be shared), showing his
		857	lack of understanding of this area - if it is hard to understand for Chip,
		858	it is probably not obvious to everybody).
		859
		860	What follows is an ultra-condensed version of my talk about threads in
		861	scripting languages given onthe perl workshop 2009:
		862
		863	The so-called "ithreads" were originally implemented for two reasons:
		864	first, to (badly) emulate unix processes on native win32 perls, and
		865	secondly, to replace the older, real thread model ("5.005-threads").
		866
		867	It does that by using threads instead of OS processes. The difference
		868	between processes and threads is that threads share memory (and other
		869	state, such as files) between threads within a single process, while
		870	processes do not share anything (at least not semantically). That
		871	means that modifications done by one thread are seen by others, while
		872	modifications by one process are not seen by other processes.
		873
		874	The "ithreads" work exactly like that: when creating a new ithreads
		875	process, all state is copied (memory is copied physically, files and code
		876	is copied logically). Afterwards, it isolates all modifications. On UNIX,
		877	the same behaviour can be achieved by using operating system processes,
		878	except that UNIX typically uses hardware built into the system to do this
		879	efficiently, while the windows process emulation emulates this hardware in
		880	software (rather efficiently, but of course it is still much slower than
		881	dedicated hardware).
		882
		883	As mentioned before, loading code, modifying code, modifying data
		884	structures and so on is only visible in the ithreads process doing the
		885	modification, not in other ithread processes within the same OS process.
		886
		887	This is why "ithreads" do not implement threads for perl at all, only
		888	processes. What makes it so bad is that on non-windows platforms, you can
		889	actually take advantage of custom hardware for this purpose (as evidenced
		890	by the forks module, which gives you the (i-) threads API, just much
		891	faster).
		892
		893	Sharing data is in the i-threads model is done by transfering data
		894	structures between threads using copying semantics, which is very slow -
		895	shared data simply does not exist. Benchmarks using i-threads which are
		896	communication-intensive show extremely bad behaviour with i-threads (in
		897	fact, so bad that Coro, which cannot take direct advantage of multiple
		898	CPUs, is often orders of magnitude faster because it shares data using
		899	real threads, refer to my talk for details).
		900
		901	As summary, i-threads use threads to implement processes, while
		902	the compatible forks module uses processes to emulate, uhm,
		903	processes. I-threads slow down every perl program when enabled, and
		904	outside of windows, serve no (or little) practical purpose, but
		905	disadvantages every single-threaded Perl program.
		906
		907	This is the reason that I try to avoid the name "ithreads", as it is
		908	misleading as it implies that it implements some kind of thread model for
		909	perl, and prefer the name "windows process emulation", which describes the
		910	actual use and behaviour of it much better.
		911
807	=head1 SEE ALSO	912	=head1 SEE ALSO
808		913
809	Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.	914	Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.
810		915
811	Debugging: L<Coro::Debug>.	916	Debugging: L<Coro::Debug>.

Diff Legend

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

Comparing cvsroot/Coro/Coro.pm (file contents): Revision 1.248 by root, Mon Dec 15 15:03:31 2008 UTC vs. Revision 1.274 by root, Sat Dec 12 01:30:26 2009 UTC

Diff Legend

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.248 by root, Mon Dec 15 15:03:31 2008 UTC vs.
Revision 1.274 by root, Sat Dec 12 01:30:26 2009 UTC