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

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.249 by root, Mon Dec 15 15:21:25 2008 UTC vs.
Revision 1.280 by root, Thu Nov 11 15:07:16 2010 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.13;	86	our $VERSION = 5.25;
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 rouse_cb rouse_wait);
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	);
91	our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));	92	our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
92		93
…		…
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	# \|\|= because other modules could have provided their own by now
158	require Carp;	144	$idle \|\|= new Coro sub {
159	Carp::croak ("FATAL: deadlock detected");	145	require Coro::Debug;
		146	die "FATAL: deadlock detected.\n"
		147	. Coro::Debug::ps_listing ();
160	};	148	};
161		149
162	# this coro is necessary because a coro	150	# this coro is necessary because a coro
163	# cannot destroy itself.	151	# cannot destroy itself.
164	our @destroy;	152	our @destroy;
…		…
206	Example: Create a new coro that just prints its arguments.	194	Example: Create a new coro that just prints its arguments.
207		195
208	async {	196	async {
209	print "@_\n";	197	print "@_\n";
210	} 1,2,3,4;	198	} 1,2,3,4;
211
212	=cut
213
214	sub async(&@) {
215	my $coro = new Coro @_;
216	$coro->ready;
217	$coro
218	}
219		199
220	=item async_pool { ... } [@args...]	200	=item async_pool { ... } [@args...]
221		201
222	Similar to C<async>, but uses a coro pool, so you should not call	202	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	203	terminate or join on it (although you are allowed to), and you get a
…		…
280	=item schedule	260	=item schedule
281		261
282	Calls the scheduler. The scheduler will find the next coro that is	262	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	263	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	264	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	265	in its ready queue. If there is no coro ready, it will call the
286	C<$Coro::idle> hook.	266	C<$Coro::idle> hook.
287		267
288	Please note that the current coro will I<not> be put into the ready	268	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	269	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 >>,	270	again unless something else (e.g. an event handler) calls C<< ->ready >>,
…		…
338		318
339	These functions implement the same concept as C<dynamic-wind> in scheme	319	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	320	does, and are useful when you want to localise some resource to a specific
341	coro.	321	coro.
342		322
343	They slow down coro switching considerably for coros that use	323	They slow down thread switching considerably for coros that use them
344	them (But coro switching is still reasonably fast if the handlers are	324	(about 40% for a BLOCK with a single assignment, so thread switching is
345	fast).	325	still reasonably fast if the handlers are fast).
346		326
347	These functions are best understood by an example: The following function	327	These functions are best understood by an example: The following function
348	will change the current timezone to "Antarctica/South_Pole", which	328	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>,	329	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	330	which remember/change the current timezone and restore the previous
351	value, respectively, the timezone is only changes for the coro that	331	value, respectively, the timezone is only changed for the coro that
352	installed those handlers.	332	installed those handlers.
353		333
354	use POSIX qw(tzset);	334	use POSIX qw(tzset);
355		335
356	async {	336	async {
…		…
373	};	353	};
374		354
375	This can be used to localise about any resource (locale, uid, current	355	This can be used to localise about any resource (locale, uid, current
376	working directory etc.) to a block, despite the existance of other	356	working directory etc.) to a block, despite the existance of other
377	coros.	357	coros.
		358
		359	Another interesting example implements time-sliced multitasking using
		360	interval timers (this could obviously be optimised, but does the job):
		361
		362	# "timeslice" the given block
		363	sub timeslice(&) {
		364	use Time::HiRes ();
		365
		366	Coro::on_enter {
		367	# on entering the thread, we set an VTALRM handler to cede
		368	$SIG{VTALRM} = sub { cede };
		369	# and then start the interval timer
		370	Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01;
		371	};
		372	Coro::on_leave {
		373	# on leaving the thread, we stop the interval timer again
		374	Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0;
		375	};
		376
		377	&{+shift};
		378	}
		379
		380	# use like this:
		381	timeslice {
		382	# The following is an endless loop that would normally
		383	# monopolise the process. Since it runs in a timesliced
		384	# environment, it will regularly cede to other threads.
		385	while () { }
		386	};
		387
378		388
379	=item killall	389	=item killall
380		390
381	Kills/terminates/cancels all coros except the currently running one.	391	Kills/terminates/cancels all coros except the currently running one.
382		392
…		…
426	the ready queue, do nothing and return false.	436	the ready queue, do nothing and return false.
427		437
428	This ensures that the scheduler will resume this coro automatically	438	This ensures that the scheduler will resume this coro automatically
429	once all the coro of higher priority and all coro of the same	439	once all the coro of higher priority and all coro of the same
430	priority that were put into the ready queue earlier have been resumed.	440	priority that were put into the ready queue earlier have been resumed.
		441
		442	=item $coro->suspend
		443
		444	Suspends the specified coro. A suspended coro works just like any other
		445	coro, except that the scheduler will not select a suspended coro for
		446	execution.
		447
		448	Suspending a coro can be useful when you want to keep the coro from
		449	running, but you don't want to destroy it, or when you want to temporarily
		450	freeze a coro (e.g. for debugging) to resume it later.
		451
		452	A scenario for the former would be to suspend all (other) coros after a
		453	fork and keep them alive, so their destructors aren't called, but new
		454	coros can be created.
		455
		456	=item $coro->resume
		457
		458	If the specified coro was suspended, it will be resumed. Note that when
		459	the coro was in the ready queue when it was suspended, it might have been
		460	unreadied by the scheduler, so an activation might have been lost.
		461
		462	To avoid this, it is best to put a suspended coro into the ready queue
		463	unconditionally, as every synchronisation mechanism must protect itself
		464	against spurious wakeups, and the one in the Coro family certainly do
		465	that.
431		466
432	=item $is_ready = $coro->is_ready	467	=item $is_ready = $coro->is_ready
433		468
434	Returns true iff the Coro object is in the ready queue. Unless the Coro	469	Returns true iff the Coro object is in the ready queue. Unless the Coro
435	object gets destroyed, it will eventually be scheduled by the scheduler.	470	object gets destroyed, it will eventually be scheduled by the scheduler.
…		…
578	Sets (or gets in case the argument is missing) the description for this	613	Sets (or gets in case the argument is missing) the description for this
579	coro. This is just a free-form string you can associate with a	614	coro. This is just a free-form string you can associate with a
580	coro.	615	coro.
581		616
582	This method simply sets the C<< $coro->{desc} >> member to the given	617	This method simply sets the C<< $coro->{desc} >> member to the given
583	string. You can modify this member directly if you wish.	618	string. You can modify this member directly if you wish, and in fact, this
		619	is often preferred to indicate major processing states that cna then be
		620	seen for example in a L<Coro::Debug> session:
		621
		622	sub my_long_function {
		623	local $Coro::current->{desc} = "now in my_long_function";
		624	...
		625	$Coro::current->{desc} = "my_long_function: phase 1";
		626	...
		627	$Coro::current->{desc} = "my_long_function: phase 2";
		628	...
		629	}
584		630
585	=cut	631	=cut
586		632
587	sub desc {	633	sub desc {
588	my $old = $_[0]{desc};	634	my $old = $_[0]{desc};
…		…
630	The reason this function exists is that many event libraries (such as the	676	The reason this function exists is that many event libraries (such as the
631	venerable L<Event\|Event> module) are not thread-safe (a weaker form	677	venerable L<Event\|Event> module) are not thread-safe (a weaker form
632	of reentrancy). This means you must not block within event callbacks,	678	of reentrancy). This means you must not block within event callbacks,
633	otherwise you might suffer from crashes or worse. The only event library	679	otherwise you might suffer from crashes or worse. The only event library
634	currently known that is safe to use without C<unblock_sub> is L<EV>.	680	currently known that is safe to use without C<unblock_sub> is L<EV>.
		681
		682	Coro will try to catch you when you block in the event loop
		683	("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and
		684	only works when you do not run your own event loop.
635		685
636	This function allows your callbacks to block by executing them in another	686	This function allows your callbacks to block by executing them in another
637	coro where it is safe to block. One example where blocking is handy	687	coro where it is safe to block. One example where blocking is handy
638	is when you use the L<Coro::AIO\|Coro::AIO> functions to save results to	688	is when you use the L<Coro::AIO\|Coro::AIO> functions to save results to
639	disk, for example.	689	disk, for example.
…		…
681	unshift @unblock_queue, [$cb, @_];	731	unshift @unblock_queue, [$cb, @_];
682	$unblock_scheduler->ready;	732	$unblock_scheduler->ready;
683	}	733	}
684	}	734	}
685		735
686	=item $cb = Coro::rouse_cb	736	=item $cb = rouse_cb
687		737
688	Create and return a "rouse callback". That's a code reference that,	738	Create and return a "rouse callback". That's a code reference that,
689	when called, will remember a copy of its arguments and notify the owner	739	when called, will remember a copy of its arguments and notify the owner
690	coro of the callback.	740	coro of the callback.
691		741
692	See the next function.	742	See the next function.
693		743
694	=item @args = Coro::rouse_wait [$cb]	744	=item @args = rouse_wait [$cb]
695		745
696	Wait for the specified rouse callback (or the last one that was created in	746	Wait for the specified rouse callback (or the last one that was created in
697	this coro).	747	this coro).
698		748
699	As soon as the callback is invoked (or when the callback was invoked	749	As soon as the callback is invoked (or when the callback was invoked
700	before C<rouse_wait>), it will return the arguments originally passed to	750	before C<rouse_wait>), it will return the arguments originally passed to
701	the rouse callback.	751	the rouse callback. In scalar context, that means you get the I<last>
		752	argument, just as if C<rouse_wait> had a C<return ($a1, $a2, $a3...)>
		753	statement at the end.
702		754
703	See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.	755	See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
704		756
705	=back	757	=back
706		758
…		…
794	the windows process emulation enabled under unix roughly halves perl	846	the windows process emulation enabled under unix roughly halves perl
795	performance, even when not used.	847	performance, even when not used.
796		848
797	=item coro switching is not signal safe	849	=item coro switching is not signal safe
798		850
799	You must not switch to another coro from within a signal handler	851	You must not switch to another coro from within a signal handler (only
800	(only relevant with %SIG - most event libraries provide safe signals).	852	relevant with %SIG - most event libraries provide safe signals), I<unless>
		853	you are sure you are not interrupting a Coro function.
801		854
802	That means you I<MUST NOT> call any function that might "block" the	855	That means you I<MUST NOT> call any function that might "block" the
803	current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or	856	current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
804	anything that calls those. Everything else, including calling C<ready>,	857	anything that calls those. Everything else, including calling C<ready>,
805	works.	858	works.
806		859
807	=back	860	=back
808		861
809		862
		863	=head1 WINDOWS PROCESS EMULATION
		864
		865	A great many people seem to be confused about ithreads (for example, Chip
		866	Salzenberg called me unintelligent, incapable, stupid and gullible,
		867	while in the same mail making rather confused statements about perl
		868	ithreads (for example, that memory or files would be shared), showing his
		869	lack of understanding of this area - if it is hard to understand for Chip,
		870	it is probably not obvious to everybody).
		871
		872	What follows is an ultra-condensed version of my talk about threads in
		873	scripting languages given onthe perl workshop 2009:
		874
		875	The so-called "ithreads" were originally implemented for two reasons:
		876	first, to (badly) emulate unix processes on native win32 perls, and
		877	secondly, to replace the older, real thread model ("5.005-threads").
		878
		879	It does that by using threads instead of OS processes. The difference
		880	between processes and threads is that threads share memory (and other
		881	state, such as files) between threads within a single process, while
		882	processes do not share anything (at least not semantically). That
		883	means that modifications done by one thread are seen by others, while
		884	modifications by one process are not seen by other processes.
		885
		886	The "ithreads" work exactly like that: when creating a new ithreads
		887	process, all state is copied (memory is copied physically, files and code
		888	is copied logically). Afterwards, it isolates all modifications. On UNIX,
		889	the same behaviour can be achieved by using operating system processes,
		890	except that UNIX typically uses hardware built into the system to do this
		891	efficiently, while the windows process emulation emulates this hardware in
		892	software (rather efficiently, but of course it is still much slower than
		893	dedicated hardware).
		894
		895	As mentioned before, loading code, modifying code, modifying data
		896	structures and so on is only visible in the ithreads process doing the
		897	modification, not in other ithread processes within the same OS process.
		898
		899	This is why "ithreads" do not implement threads for perl at all, only
		900	processes. What makes it so bad is that on non-windows platforms, you can
		901	actually take advantage of custom hardware for this purpose (as evidenced
		902	by the forks module, which gives you the (i-) threads API, just much
		903	faster).
		904
		905	Sharing data is in the i-threads model is done by transfering data
		906	structures between threads using copying semantics, which is very slow -
		907	shared data simply does not exist. Benchmarks using i-threads which are
		908	communication-intensive show extremely bad behaviour with i-threads (in
		909	fact, so bad that Coro, which cannot take direct advantage of multiple
		910	CPUs, is often orders of magnitude faster because it shares data using
		911	real threads, refer to my talk for details).
		912
		913	As summary, i-threads use threads to implement processes, while
		914	the compatible forks module uses processes to emulate, uhm,
		915	processes. I-threads slow down every perl program when enabled, and
		916	outside of windows, serve no (or little) practical purpose, but
		917	disadvantages every single-threaded Perl program.
		918
		919	This is the reason that I try to avoid the name "ithreads", as it is
		920	misleading as it implies that it implements some kind of thread model for
		921	perl, and prefer the name "windows process emulation", which describes the
		922	actual use and behaviour of it much better.
		923
810	=head1 SEE ALSO	924	=head1 SEE ALSO
811		925
812	Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.	926	Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.
813		927
814	Debugging: L<Coro::Debug>.	928	Debugging: L<Coro::Debug>.

Diff Legend

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

Comparing cvsroot/Coro/Coro.pm (file contents): Revision 1.249 by root, Mon Dec 15 15:21:25 2008 UTC vs. Revision 1.280 by root, Thu Nov 11 15:07:16 2010 UTC

Diff Legend

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.249 by root, Mon Dec 15 15:21:25 2008 UTC vs.
Revision 1.280 by root, Thu Nov 11 15:07:16 2010 UTC