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

Comparing Coro/Coro.pm (file contents):
Revision 1.287 by root, Sat Feb 19 06:51:22 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.
… …
328 330
329our $idle; # idle handler 331our $idle; # idle handler
330our $main; # main coro 332our $main; # main coro
331our $current; # current coro 333our $current; # current coro
332 334
333our $VERSION = 5.37; 335our $VERSION = 5.372;
334 336
335our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait); 337our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait);
336our %EXPORT_TAGS = ( 338our %EXPORT_TAGS = (
337 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 339 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
338); 340);
… …
399our @destroy; 401our @destroy;
400our $manager; 402our $manager;
401 403
402$manager = new Coro sub { 404$manager = new Coro sub {
403 while () { 405 while () {
404 Coro::State::cancel shift @destroy 406 _destroy shift @destroy
405 while @destroy; 407 while @destroy;
406 408
407 &schedule; 409 &schedule;
408 } 410 }
409}; 411};
… …
543coro, regardless of priority. This is useful sometimes to ensure 545coro, regardless of priority. This is useful sometimes to ensure
544progress is made. 546progress is made.
545 547
546=item terminate [arg...] 548=item terminate [arg...]
547 549
548Terminates the current coro with the given status values (see L<cancel>). 550Terminates the current coro with the given status values (see
551L<cancel>). The values will not be copied, but referenced directly.
549 552
550=item Coro::on_enter BLOCK, Coro::on_leave BLOCK 553=item Coro::on_enter BLOCK, Coro::on_leave BLOCK
551 554
552These function install enter and leave winders in the current scope. The 555These function install enter and leave winders in the current scope. The
553enter block will be executed when on_enter is called and whenever the 556enter block will be executed when on_enter is called and whenever the
… …
727Returns true iff this Coro object has been suspended. Suspended Coros will 730Returns true iff this Coro object has been suspended. Suspended Coros will
728not ever be scheduled. 731not ever be scheduled.
729 732
730=item $coro->cancel (arg...) 733=item $coro->cancel (arg...)
731 734
732Terminates the given Coro and makes it return the given arguments as 735Terminates the given Coro thread and makes it return the given arguments as
733status (default: the empty list). Never returns if the Coro is the 736status (default: an empty list). Never returns if the Coro is the
734current Coro. 737current Coro.
735 738
736=cut 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.
737 744
738sub cancel { 745Sometimes it is safer to C<< ->throw >> an exception, or use C<<
739 my $self = shift; 746->safe_cancel >>.
740 747
741 if ($current == $self) { 748The arguments are not copied, but instead will be referenced directly
742 terminate @_; 749(e.g. if you pass C<$var> and after the call change that variable, then
743 } else { 750you might change the return values passed to e.g. C<join>, so don't do
744 $self->{_status} = [@_]; 751that).
745 Coro::State::cancel $self; 752
753The resources of the Coro are usually freed (or destructed) before this
754call returns, but this can be delayed for an indefinite amount of time, as
755in some cases the manager thread has to run first to actually destruct the
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: $@";
746 } 781 }
747}
748 782
749=item $coro->schedule_to 783=item $coro->schedule_to
750 784
751Puts the current coro to sleep (like C<Coro::schedule>), but instead 785Puts the current coro to sleep (like C<Coro::schedule>), but instead
752of 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
… …
790 824
791=item $coro->join 825=item $coro->join
792 826
793Wait until the coro terminates and return any values given to the 827Wait until the coro terminates and return any values given to the
794C<terminate> or C<cancel> functions. C<join> can be called concurrently 828C<terminate> or C<cancel> functions. C<join> can be called concurrently
795from multiple coro, and all will be resumed and given the status 829from multiple threads, and all will be resumed and given the status
796return once the C<$coro> terminates. 830return once the C<$coro> terminates.
797 831
798=cut 832=cut
799 833
800sub join { 834sub join {
… …
815} 849}
816 850
817=item $coro->on_destroy (\&cb) 851=item $coro->on_destroy (\&cb)
818 852
819Registers a callback that is called when this coro thread gets destroyed, 853Registers a callback that is called when this coro thread gets destroyed,
820but before it is joined. The callback gets passed the terminate arguments, 854that is, after it's resources have been freed but before it is joined. The
855callback gets passed the terminate/cancel arguments, if any, and I<must
821if any, and I<must not> die, under any circumstances. 856not> die, under any circumstances.
822 857
823There can be any number of C<on_destroy> callbacks per coro. 858There can be any number of C<on_destroy> callbacks per coro, and there is
859no way currently to remove a callback once added.
824 860
825=cut 861=cut
826 862
827sub on_destroy { 863sub on_destroy {
828 my ($self, $cb) = @_; 864 my ($self, $cb) = @_;

Diff Legend

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