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

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.264 by root, Thu Aug 13 02:35:41 2009 UTC vs.
Revision 1.285 by root, Thu Feb 17 01:32:18 2011 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.162;	86	our $VERSION = 5.26;
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 wakes 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;
…		…
272	=item schedule	260	=item schedule
273		261
274	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
275	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
276	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
277	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
278	C<$Coro::idle> hook.	266	C<$Coro::idle> hook.
279		267
280	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
281	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
282	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 >>,
…		…
579	wantarray ? @{$self->{_status}} : $self->{_status}[0];	567	wantarray ? @{$self->{_status}} : $self->{_status}[0];
580	}	568	}
581		569
582	=item $coro->on_destroy (\&cb)	570	=item $coro->on_destroy (\&cb)
583		571
584	Registers a callback that is called when this coro gets destroyed,	572	Registers a callback that is called when this coro thread gets destroyed,
585	but before it is joined. The callback gets passed the terminate arguments,	573	but before it is joined. The callback gets passed the terminate arguments,
586	if any, and I<must not> die, under any circumstances.	574	if any, and I<must not> die, under any circumstances.
587		575
		576	There can be any number of C<on_destroy> callbacks per coro.
		577
588	=cut	578	=cut
589		579
590	sub on_destroy {	580	sub on_destroy {
591	my ($self, $cb) = @_;	581	my ($self, $cb) = @_;
592		582
…		…
594	}	584	}
595		585
596	=item $oldprio = $coro->prio ($newprio)	586	=item $oldprio = $coro->prio ($newprio)
597		587
598	Sets (or gets, if the argument is missing) the priority of the	588	Sets (or gets, if the argument is missing) the priority of the
599	coro. Higher priority coro get run before lower priority	589	coro thread. Higher priority coro get run before lower priority
600	coro. Priorities are small signed integers (currently -4 .. +3),	590	coros. Priorities are small signed integers (currently -4 .. +3),
601	that you can refer to using PRIO_xxx constants (use the import tag :prio	591	that you can refer to using PRIO_xxx constants (use the import tag :prio
602	to get then):	592	to get then):
603		593
604	PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN	594	PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
605	3 > 1 > 0 > -1 > -3 > -4	595	3 > 1 > 0 > -1 > -3 > -4
606		596
607	# set priority to HIGH	597	# set priority to HIGH
608	current->prio (PRIO_HIGH);	598	current->prio (PRIO_HIGH);
609		599
610	The idle coro ($Coro::idle) always has a lower priority than any	600	The idle coro thread ($Coro::idle) always has a lower priority than any
611	existing coro.	601	existing coro.
612		602
613	Changing the priority of the current coro will take effect immediately,	603	Changing the priority of the current coro will take effect immediately,
614	but changing the priority of coro in the ready queue (but not	604	but changing the priority of a coro in the ready queue (but not running)
615	running) will only take effect after the next schedule (of that	605	will only take effect after the next schedule (of that coro). This is a
616	coro). This is a bug that will be fixed in some future version.	606	bug that will be fixed in some future version.
617		607
618	=item $newprio = $coro->nice ($change)	608	=item $newprio = $coro->nice ($change)
619		609
620	Similar to C<prio>, but subtract the given value from the priority (i.e.	610	Similar to C<prio>, but subtract the given value from the priority (i.e.
621	higher values mean lower priority, just as in unix).	611	higher values mean lower priority, just as in UNIX's nice command).
622		612
623	=item $olddesc = $coro->desc ($newdesc)	613	=item $olddesc = $coro->desc ($newdesc)
624		614
625	Sets (or gets in case the argument is missing) the description for this	615	Sets (or gets in case the argument is missing) the description for this
626	coro. This is just a free-form string you can associate with a	616	coro thread. This is just a free-form string you can associate with a
627	coro.	617	coro.
628		618
629	This method simply sets the C<< $coro->{desc} >> member to the given	619	This method simply sets the C<< $coro->{desc} >> member to the given
630	string. You can modify this member directly if you wish.	620	string. You can modify this member directly if you wish, and in fact, this
		621	is often preferred to indicate major processing states that cna then be
		622	seen for example in a L<Coro::Debug> session:
		623
		624	sub my_long_function {
		625	local $Coro::current->{desc} = "now in my_long_function";
		626	...
		627	$Coro::current->{desc} = "my_long_function: phase 1";
		628	...
		629	$Coro::current->{desc} = "my_long_function: phase 2";
		630	...
		631	}
631		632
632	=cut	633	=cut
633		634
634	sub desc {	635	sub desc {
635	my $old = $_[0]{desc};	636	my $old = $_[0]{desc};
…		…
672	returning a new coderef. Unblocking means that calling the new coderef	673	returning a new coderef. Unblocking means that calling the new coderef
673	will return immediately without blocking, returning nothing, while the	674	will return immediately without blocking, returning nothing, while the
674	original code ref will be called (with parameters) from within another	675	original code ref will be called (with parameters) from within another
675	coro.	676	coro.
676		677
677	The reason this function exists is that many event libraries (such as the	678	The reason this function exists is that many event libraries (such as
678	venerable L<Event\|Event> module) are not thread-safe (a weaker form	679	the venerable L<Event\|Event> module) are not thread-safe (a weaker form
679	of reentrancy). This means you must not block within event callbacks,	680	of reentrancy). This means you must not block within event callbacks,
680	otherwise you might suffer from crashes or worse. The only event library	681	otherwise you might suffer from crashes or worse. The only event library
681	currently known that is safe to use without C<unblock_sub> is L<EV>.	682	currently known that is safe to use without C<unblock_sub> is L<EV> (but
		683	you might still run into deadlocks if all event loops are blocked).
		684
		685	Coro will try to catch you when you block in the event loop
		686	("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and
		687	only works when you do not run your own event loop.
682		688
683	This function allows your callbacks to block by executing them in another	689	This function allows your callbacks to block by executing them in another
684	coro where it is safe to block. One example where blocking is handy	690	coro where it is safe to block. One example where blocking is handy
685	is when you use the L<Coro::AIO\|Coro::AIO> functions to save results to	691	is when you use the L<Coro::AIO\|Coro::AIO> functions to save results to
686	disk, for example.	692	disk, for example.
…		…
728	unshift @unblock_queue, [$cb, @_];	734	unshift @unblock_queue, [$cb, @_];
729	$unblock_scheduler->ready;	735	$unblock_scheduler->ready;
730	}	736	}
731	}	737	}
732		738
733	=item $cb = Coro::rouse_cb	739	=item $cb = rouse_cb
734		740
735	Create and return a "rouse callback". That's a code reference that,	741	Create and return a "rouse callback". That's a code reference that,
736	when called, will remember a copy of its arguments and notify the owner	742	when called, will remember a copy of its arguments and notify the owner
737	coro of the callback.	743	coro of the callback.
738		744
739	See the next function.	745	See the next function.
740		746
741	=item @args = Coro::rouse_wait [$cb]	747	=item @args = rouse_wait [$cb]
742		748
743	Wait for the specified rouse callback (or the last one that was created in	749	Wait for the specified rouse callback (or the last one that was created in
744	this coro).	750	this coro).
745		751
746	As soon as the callback is invoked (or when the callback was invoked	752	As soon as the callback is invoked (or when the callback was invoked
…		…
752	See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.	758	See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
753		759
754	=back	760	=back
755		761
756	=cut	762	=cut
		763
		764	for my $module (qw(Channel RWLock Semaphore SemaphoreSet Signal Specific)) {
		765	my $old = defined &{"Coro::$module\::new"} && \&{"Coro::$module\::new"};
		766
		767	*{"Coro::$module\::new"} = sub {
		768	require "Coro/$module.pm";
		769
		770	# some modules have their new predefined in State.xs, some don't
		771	*{"Coro::$module\::new"} = $old
		772	if $old;
		773
		774	goto &{"Coro::$module\::new"};
		775	};
		776	}
757		777
758	1;	778	1;
759		779
760	=head1 HOW TO WAIT FOR A CALLBACK	780	=head1 HOW TO WAIT FOR A CALLBACK
761		781
…		…
843	the windows process emulation enabled under unix roughly halves perl	863	the windows process emulation enabled under unix roughly halves perl
844	performance, even when not used.	864	performance, even when not used.
845		865
846	=item coro switching is not signal safe	866	=item coro switching is not signal safe
847		867
848	You must not switch to another coro from within a signal handler	868	You must not switch to another coro from within a signal handler (only
849	(only relevant with %SIG - most event libraries provide safe signals).	869	relevant with %SIG - most event libraries provide safe signals), I<unless>
		870	you are sure you are not interrupting a Coro function.
850		871
851	That means you I<MUST NOT> call any function that might "block" the	872	That means you I<MUST NOT> call any function that might "block" the
852	current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or	873	current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
853	anything that calls those. Everything else, including calling C<ready>,	874	anything that calls those. Everything else, including calling C<ready>,
854	works.	875	works.
855		876
856	=back	877	=back
857		878
858		879
		880	=head1 WINDOWS PROCESS EMULATION
		881
		882	A great many people seem to be confused about ithreads (for example, Chip
		883	Salzenberg called me unintelligent, incapable, stupid and gullible,
		884	while in the same mail making rather confused statements about perl
		885	ithreads (for example, that memory or files would be shared), showing his
		886	lack of understanding of this area - if it is hard to understand for Chip,
		887	it is probably not obvious to everybody).
		888
		889	What follows is an ultra-condensed version of my talk about threads in
		890	scripting languages given on the perl workshop 2009:
		891
		892	The so-called "ithreads" were originally implemented for two reasons:
		893	first, to (badly) emulate unix processes on native win32 perls, and
		894	secondly, to replace the older, real thread model ("5.005-threads").
		895
		896	It does that by using threads instead of OS processes. The difference
		897	between processes and threads is that threads share memory (and other
		898	state, such as files) between threads within a single process, while
		899	processes do not share anything (at least not semantically). That
		900	means that modifications done by one thread are seen by others, while
		901	modifications by one process are not seen by other processes.
		902
		903	The "ithreads" work exactly like that: when creating a new ithreads
		904	process, all state is copied (memory is copied physically, files and code
		905	is copied logically). Afterwards, it isolates all modifications. On UNIX,
		906	the same behaviour can be achieved by using operating system processes,
		907	except that UNIX typically uses hardware built into the system to do this
		908	efficiently, while the windows process emulation emulates this hardware in
		909	software (rather efficiently, but of course it is still much slower than
		910	dedicated hardware).
		911
		912	As mentioned before, loading code, modifying code, modifying data
		913	structures and so on is only visible in the ithreads process doing the
		914	modification, not in other ithread processes within the same OS process.
		915
		916	This is why "ithreads" do not implement threads for perl at all, only
		917	processes. What makes it so bad is that on non-windows platforms, you can
		918	actually take advantage of custom hardware for this purpose (as evidenced
		919	by the forks module, which gives you the (i-) threads API, just much
		920	faster).
		921
		922	Sharing data is in the i-threads model is done by transfering data
		923	structures between threads using copying semantics, which is very slow -
		924	shared data simply does not exist. Benchmarks using i-threads which are
		925	communication-intensive show extremely bad behaviour with i-threads (in
		926	fact, so bad that Coro, which cannot take direct advantage of multiple
		927	CPUs, is often orders of magnitude faster because it shares data using
		928	real threads, refer to my talk for details).
		929
		930	As summary, i-threads use threads to implement processes, while
		931	the compatible forks module uses processes to emulate, uhm,
		932	processes. I-threads slow down every perl program when enabled, and
		933	outside of windows, serve no (or little) practical purpose, but
		934	disadvantages every single-threaded Perl program.
		935
		936	This is the reason that I try to avoid the name "ithreads", as it is
		937	misleading as it implies that it implements some kind of thread model for
		938	perl, and prefer the name "windows process emulation", which describes the
		939	actual use and behaviour of it much better.
		940
859	=head1 SEE ALSO	941	=head1 SEE ALSO
860		942
861	Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.	943	Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.
862		944
863	Debugging: L<Coro::Debug>.	945	Debugging: L<Coro::Debug>.

Diff Legend

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

Comparing cvsroot/Coro/Coro.pm (file contents): Revision 1.264 by root, Thu Aug 13 02:35:41 2009 UTC vs. Revision 1.285 by root, Thu Feb 17 01:32:18 2011 UTC

Diff Legend

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.264 by root, Thu Aug 13 02:35:41 2009 UTC vs.
Revision 1.285 by root, Thu Feb 17 01:32:18 2011 UTC