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

Comparing Coro/Coro.pm (file contents):
Revision 1.287 by root, Sat Feb 19 06:51:22 2011 UTC vs.
Revision 1.296 by root, Thu May 12 23:24:28 2011 UTC

…		…
196		196
197	async {	197	async {
198	Coro::terminate "return value 1", "return value 2";	198	Coro::terminate "return value 1", "return value 2";
199	};	199	};
200		200
201	And yet another way is to C<< ->cancel >> the coro thread from another	201	And yet another way is to C<< ->cancel >> (or C<< ->safe_cancel >>) the
202	thread:	202	coro thread from another thread:
203		203
204	my $coro = async {	204	my $coro = async {
205	exit 1;	205	exit 1;
206	};	206	};
207		207
208	$coro->cancel; # an also accept values for ->join to retrieve	208	$coro->cancel; # also accepts values for ->join to retrieve
209		209
210	Cancellation I<can> be dangerous - it's a bit like calling C<exit> without	210	Cancellation I<can> be dangerous - it's a bit like calling C<exit> without
211	actually exiting, and might leave C libraries and XS modules in a weird	211	actually exiting, and might leave C libraries and XS modules in a weird
212	state. Unlike other thread implementations, however, Coro is exceptionally	212	state. Unlike other thread implementations, however, Coro is exceptionally
213	safe with regards to cancellation, as perl will always be in a consistent	213	safe with regards to cancellation, as perl will always be in a consistent
214	state.	214	state, and for those cases where you want to do truly marvellous things
		215	with your coro while it is being cancelled - that is, make sure all
		216	cleanup code is executed from the thread being cancelled - there is even a
		217	C<< ->safe_cancel >> method.
215		218
216	So, cancelling a thread that runs in an XS event loop might not be the	219	So, cancelling a thread that runs in an XS event loop might not be the
217	best idea, but any other combination that deals with perl only (cancelling	220	best idea, but any other combination that deals with perl only (cancelling
218	when a thread is in a C<tie> method or an C<AUTOLOAD> for example) is	221	when a thread is in a C<tie> method or an C<AUTOLOAD> for example) is
219	safe.	222	safe.
…		…
328		331
329	our $idle; # idle handler	332	our $idle; # idle handler
330	our $main; # main coro	333	our $main; # main coro
331	our $current; # current coro	334	our $current; # current coro
332		335
333	our $VERSION = 5.37;	336	our $VERSION = 5.372;
334		337
335	our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait);	338	our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait);
336	our %EXPORT_TAGS = (	339	our %EXPORT_TAGS = (
337	prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],	340	prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
338	);	341	);
…		…
399	our @destroy;	402	our @destroy;
400	our $manager;	403	our $manager;
401		404
402	$manager = new Coro sub {	405	$manager = new Coro sub {
403	while () {	406	while () {
404	Coro::State::cancel shift @destroy	407	_destroy shift @destroy
405	while @destroy;	408	while @destroy;
406		409
407	&schedule;	410	&schedule;
408	}	411	}
409	};	412	};
…		…
543	coro, regardless of priority. This is useful sometimes to ensure	546	coro, regardless of priority. This is useful sometimes to ensure
544	progress is made.	547	progress is made.
545		548
546	=item terminate [arg...]	549	=item terminate [arg...]
547		550
548	Terminates the current coro with the given status values (see L<cancel>).	551	Terminates the current coro with the given status values (see
		552	L<cancel>). The values will not be copied, but referenced directly.
549		553
550	=item Coro::on_enter BLOCK, Coro::on_leave BLOCK	554	=item Coro::on_enter BLOCK, Coro::on_leave BLOCK
551		555
552	These function install enter and leave winders in the current scope. The	556	These function install enter and leave winders in the current scope. The
553	enter block will be executed when on_enter is called and whenever the	557	enter block will be executed when on_enter is called and whenever the
…		…
727	Returns true iff this Coro object has been suspended. Suspended Coros will	731	Returns true iff this Coro object has been suspended. Suspended Coros will
728	not ever be scheduled.	732	not ever be scheduled.
729		733
730	=item $coro->cancel (arg...)	734	=item $coro->cancel (arg...)
731		735
732	Terminates the given Coro and makes it return the given arguments as	736	Terminates the given Coro thread and makes it return the given arguments as
733	status (default: the empty list). Never returns if the Coro is the	737	status (default: an empty list). Never returns if the Coro is the
734	current Coro.	738	current Coro.
735		739
736	=cut	740	This is a rather brutal way to free a coro, with some limitations - if
		741	the thread is inside a C callback that doesn't expect to be canceled,
		742	bad things can happen, or if the cancelled thread insists on running
		743	complicated cleanup handlers that rely on it'S thread context, things will
		744	not work.
737		745
738	sub cancel {	746	Any cleanup code being run (e.g. from C<guard> blocks) will be run without
739	my $self = shift;	747	a thread context, and is not allowed to switch to other threads. On the
		748	plus side, C<< ->cancel >> will always clean up the thread, no matter
		749	what. If your cleanup code is complex or you want to avoid cancelling a
		750	C-thread that doesn't know how to clean up itself, it can be better to C<<
		751	->throw >> an exception, or use C<< ->safe_cancel >>.
740		752
741	if ($current == $self) {	753	The arguments to C<< ->cancel >> are not copied, but instead will
742	terminate @_;	754	be referenced directly (e.g. if you pass C<$var> and after the call
743	} else {	755	change that variable, then you might change the return values passed to
744	$self->{_status} = [@_];	756	e.g. C<join>, so don't do that).
745	Coro::State::cancel $self;	757
		758	The resources of the Coro are usually freed (or destructed) before this
		759	call returns, but this can be delayed for an indefinite amount of time, as
		760	in some cases the manager thread has to run first to actually destruct the
		761	Coro object.
		762
		763	=item $coro->safe_cancel ($arg...)
		764
		765	Works mostly like C<< ->cancel >>, but is inherently "safer", and
		766	consequently, can fail with an exception in cases the thread is not in a
		767	cancellable state.
		768
		769	This method works a bit like throwing an exception that cannot be caught
		770	- specifically, it will clean up the thread from within itself, so
		771	all cleanup handlers (e.g. C<guard> blocks) are run with full thread
		772	context and can block if they wish. The downside is that there is no
		773	guarantee that the thread can be cancelled when you call this method, and
		774	therefore, it might fail. It is also considerably slower than C<cancel> or
		775	C<terminate>.
		776
		777	A thread is in a safe-cancellable state if it either hasn't been run yet,
		778	or it has no C context attached and is inside an SLF function.
		779
		780	The latter two basically mean that the thread isn't currently inside a
		781	perl callback called from some C function (usually via some XS modules)
		782	and isn't currently executing inside some C function itself (via Coro's XS
		783	API).
		784
		785	This call returns true when it could cancel the thread, or croaks with an
		786	error otherwise (i.e. it either returns true or doesn't return at all).
		787
		788	Why the weird interface? Well, there are two common models on how and
		789	when to cancel things. In the first, you have the expectation that your
		790	coro thread can be cancelled when you want to cancel it - if the thread
		791	isn't cancellable, this would be a bug somewhere, so C<< ->safe_cancel >>
		792	croaks to notify of the bug.
		793
		794	In the second model you sometimes want to ask nicely to cancel a thread,
		795	but if it's not a good time, well, then don't cancel. This can be done
		796	relatively easy like this:
		797
		798	if (! eval { $coro->safe_cancel }) {
		799	warn "unable to cancel thread: $@";
746	}	800	}
747	}	801
		802	However, what you never should do is first try to cancel "safely" and
		803	if that fails, cancel the "hard" way with C<< ->cancel >>. That makes
		804	no sense: either you rely on being able to execute cleanup code in your
		805	thread context, or you don't. If you do, then C<< ->safe_cancel >> is the
		806	only way, and if you don't, then C<< ->cancel >> is always faster and more
		807	direct.
748		808
749	=item $coro->schedule_to	809	=item $coro->schedule_to
750		810
751	Puts the current coro to sleep (like C<Coro::schedule>), but instead	811	Puts the current coro to sleep (like C<Coro::schedule>), but instead
752	of continuing with the next coro from the ready queue, always switch to	812	of continuing with the next coro from the ready queue, always switch to
…		…
771	inside the coro at the next convenient point in time. Otherwise	831	inside the coro at the next convenient point in time. Otherwise
772	clears the exception object.	832	clears the exception object.
773		833
774	Coro will check for the exception each time a schedule-like-function	834	Coro will check for the exception each time a schedule-like-function
775	returns, i.e. after each C<schedule>, C<cede>, C<< Coro::Semaphore->down	835	returns, i.e. after each C<schedule>, C<cede>, C<< Coro::Semaphore->down
776	>>, C<< Coro::Handle->readable >> and so on. Most of these functions	836	>>, C<< Coro::Handle->readable >> and so on. Most of those functions (all
777	detect this case and return early in case an exception is pending.	837	that are part of Coro itself) detect this case and return early in case an
		838	exception is pending.
778		839
779	The exception object will be thrown "as is" with the specified scalar in	840	The exception object will be thrown "as is" with the specified scalar in
780	C<$@>, i.e. if it is a string, no line number or newline will be appended	841	C<$@>, i.e. if it is a string, no line number or newline will be appended
781	(unlike with C<die>).	842	(unlike with C<die>).
782		843
783	This can be used as a softer means than C<cancel> to ask a coro to	844	This can be used as a softer means than either C<cancel> or C<safe_cancel
784	end itself, although there is no guarantee that the exception will lead to	845	>to ask a coro to end itself, although there is no guarantee that the
785	termination, and if the exception isn't caught it might well end the whole	846	exception will lead to termination, and if the exception isn't caught it
786	program.	847	might well end the whole program.
787		848
788	You might also think of C<throw> as being the moral equivalent of	849	You might also think of C<throw> as being the moral equivalent of
789	C<kill>ing a coro with a signal (in this case, a scalar).	850	C<kill>ing a coro with a signal (in this case, a scalar).
790		851
791	=item $coro->join	852	=item $coro->join
792		853
793	Wait until the coro terminates and return any values given to the	854	Wait until the coro terminates and return any values given to the
794	C<terminate> or C<cancel> functions. C<join> can be called concurrently	855	C<terminate> or C<cancel> functions. C<join> can be called concurrently
795	from multiple coro, and all will be resumed and given the status	856	from multiple threads, and all will be resumed and given the status
796	return once the C<$coro> terminates.	857	return once the C<$coro> terminates.
797		858
798	=cut	859	=cut
799		860
800	sub join {	861	sub xjoin {
801	my $self = shift;	862	my $self = shift;
802		863
803	unless ($self->{_status}) {	864	unless ($self->{_status}) {
804	my $current = $current;	865	my $current = $current;
805		866
…		…
809	};	870	};
810		871
811	&schedule while $current;	872	&schedule while $current;
812	}	873	}
813		874
814	wantarray ? @{$self->{_status}} : $self->{_status}[0];	875	wantarray ? @{$self->{_status}} : $self->{_status}[0]
815	}	876	}
816		877
817	=item $coro->on_destroy (\&cb)	878	=item $coro->on_destroy (\&cb)
818		879
819	Registers a callback that is called when this coro thread gets destroyed,	880	Registers a callback that is called when this coro thread gets destroyed,
820	but before it is joined. The callback gets passed the terminate arguments,	881	that is, after it's resources have been freed but before it is joined. The
		882	callback gets passed the terminate/cancel arguments, if any, and I<must
821	if any, and I<must not> die, under any circumstances.	883	not> die, under any circumstances.
822		884
823	There can be any number of C<on_destroy> callbacks per coro.	885	There can be any number of C<on_destroy> callbacks per coro, and there is
		886	no way currently to remove a callback once added.
824		887
825	=cut	888	=cut
826		889
827	sub on_destroy {	890	sub xon_destroy {
828	my ($self, $cb) = @_;	891	my ($self, $cb) = @_;
829		892
830	push @{ $self->{_on_destroy} }, $cb;	893	push @{ $self->{_on_destroy} }, $cb;
831	}	894	}
832		895
…		…
1108	future to allow per-thread schedulers, but Coro::State does not yet allow	1171	future to allow per-thread schedulers, but Coro::State does not yet allow
1109	this). I recommend disabling thread support and using processes, as having	1172	this). I recommend disabling thread support and using processes, as having
1110	the windows process emulation enabled under unix roughly halves perl	1173	the windows process emulation enabled under unix roughly halves perl
1111	performance, even when not used.	1174	performance, even when not used.
1112		1175
		1176	Attempts to use threads created in another emulated process will crash
		1177	("cleanly", with a null pointer exception).
		1178
1113	=item coro switching is not signal safe	1179	=item coro switching is not signal safe
1114		1180
1115	You must not switch to another coro from within a signal handler (only	1181	You must not switch to another coro from within a signal handler (only
1116	relevant with %SIG - most event libraries provide safe signals), I<unless>	1182	relevant with %SIG - most event libraries provide safe signals), I<unless>
1117	you are sure you are not interrupting a Coro function.	1183	you are sure you are not interrupting a Coro function.

Diff Legend

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

Comparing Coro/Coro.pm (file contents): Revision 1.287 by root, Sat Feb 19 06:51:22 2011 UTC vs. Revision 1.296 by root, Thu May 12 23:24:28 2011 UTC

Diff Legend

Comparing Coro/Coro.pm (file contents):
Revision 1.287 by root, Sat Feb 19 06:51:22 2011 UTC vs.
Revision 1.296 by root, Thu May 12 23:24:28 2011 UTC