ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Coro/Coro.pm
(Generate patch)

Comparing Coro/Coro.pm (file contents):
Revision 1.293 by root, Sat Apr 30 05:20:03 2011 UTC vs.
Revision 1.294 by root, Fri May 6 21:15:17 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
201And yet another way is to C<< ->cancel >> the coro thread from another 201And yet another way is to C<< ->cancel >> (or C<< ->safe_cancel >>) the
202thread: 202coro 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; # an also accept values for ->join to retrieve
209 209
210Cancellation I<can> be dangerous - it's a bit like calling C<exit> without 210Cancellation I<can> be dangerous - it's a bit like calling C<exit>
211actually exiting, and might leave C libraries and XS modules in a weird 211without actually exiting, and might leave C libraries and XS modules in
212state. Unlike other thread implementations, however, Coro is exceptionally 212a weird state. Unlike other thread implementations, however, Coro is
213safe with regards to cancellation, as perl will always be in a consistent 213exceptionally safe with regards to cancellation, as perl will always be
214state. 214in a consistent state, and for those cases where you want to do truly
215marvellous things with your coro while it is being cancelled, there is
216even a C<< ->safe_cancel >> method.
215 217
216So, cancelling a thread that runs in an XS event loop might not be the 218So, cancelling a thread that runs in an XS event loop might not be the
217best idea, but any other combination that deals with perl only (cancelling 219best idea, but any other combination that deals with perl only (cancelling
218when a thread is in a C<tie> method or an C<AUTOLOAD> for example) is 220when a thread is in a C<tie> method or an C<AUTOLOAD> for example) is
219safe. 221safe.
… …
728Returns true iff this Coro object has been suspended. Suspended Coros will 730Returns true iff this Coro object has been suspended. Suspended Coros will
729not ever be scheduled. 731not ever be scheduled.
730 732
731=item $coro->cancel (arg...) 733=item $coro->cancel (arg...)
732 734
733Terminates the given Coro object and makes it return the given arguments as 735Terminates the given Coro thread and makes it return the given arguments as
734status (default: an empty list). Never returns if the Coro is the 736status (default: an empty list). Never returns if the Coro is the
735current Coro. 737current Coro.
738
739This is a rather brutal way to free a coro, with some limitations - if
740the thread is inside a C callback that doesn't expect to be canceled,
741bad things can happen, or if the cancelled thread insists on running
742complicated cleanup handlers that rely on it'S thread context, things will
743not work.
744
745Sometimes it is safer to C<< ->throw >> an exception, or use C<<
746->safe_cancel >>.
736 747
737The arguments are not copied, but instead will be referenced directly 748The arguments are not copied, but instead will be referenced directly
738(e.g. if you pass C<$var> and after the call change that variable, then 749(e.g. if you pass C<$var> and after the call change that variable, then
739you might change the return values passed to e.g. C<join>, so don't do 750you might change the return values passed to e.g. C<join>, so don't do
740that). 751that).
741 752
742The resources of the Coro are usually freed (or destructed) before this 753The resources of the Coro are usually freed (or destructed) before this
743call returns, but this can be delayed for an indefinite amount of time, as 754call returns, but this can be delayed for an indefinite amount of time, as
744in some cases the manager thread has to run first to actually destruct the 755in some cases the manager thread has to run first to actually destruct the
745Coro object. 756Coro object.
757
758=item $coro->safe_cancel ($arg...)
759
760Works mostly like C<< ->cancel >>, but is inherently "safer", and
761consequently, can fail with an exception in cases the thread is not in a
762cancellable state.
763
764This method works a bit like throwing an exception that cannot be caught
765- specifically, it will clean up the thread from within itself, so all
766cleanup handlers (e.g. C<guard> blocks) are run with full thread context
767and can block if they wish.
768
769A thread is safe-cancellable if it either hasn't been run yet, or
770it has no C context attached and is inside an SLF function.
771
772The latter two basically mean that the thread isn't currently inside a
773perl callback called from some C function (usually XS modules) and isn't
774currently inside some C function itself.
775
776This call always returns true when it could cancel the thread, or croaks
777with an error otherwise, so you can write things like this:
778
779 if (! eval { $coro->safe_cancel }) {
780 warn "unable to cancel thread: $@";
781 }
746 782
747=item $coro->schedule_to 783=item $coro->schedule_to
748 784
749Puts the current coro to sleep (like C<Coro::schedule>), but instead 785Puts the current coro to sleep (like C<Coro::schedule>), but instead
750of continuing with the next coro from the ready queue, always switch to 786of continuing with the next coro from the ready queue, always switch to

Diff Legend

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