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

Comparing Coro/Coro.pm (file contents):
Revision 1.321 by root, Sun Feb 2 03:26:06 2014 UTC vs.
Revision 1.337 by root, Sun Oct 4 13:10:22 2015 UTC

… …
366 366
367our $idle; # idle handler 367our $idle; # idle handler
368our $main; # main coro 368our $main; # main coro
369our $current; # current coro 369our $current; # current coro
370 370
371our $VERSION = 6.33; 371our $VERSION = 6.48;
372 372
373our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait); 373our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait);
374our %EXPORT_TAGS = ( 374our %EXPORT_TAGS = (
375 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 375 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
376); 376);
… …
652 Coro::on_enter { 652 Coro::on_enter {
653 # on entering the thread, we set an VTALRM handler to cede 653 # on entering the thread, we set an VTALRM handler to cede
654 $SIG{VTALRM} = sub { cede }; 654 $SIG{VTALRM} = sub { cede };
655 # and then start the interval timer 655 # and then start the interval timer
656 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01; 656 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01;
657 }; 657 };
658 Coro::on_leave { 658 Coro::on_leave {
659 # on leaving the thread, we stop the interval timer again 659 # on leaving the thread, we stop the interval timer again
660 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0; 660 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0;
661 }; 661 };
662 662
663 &{+shift}; 663 &{+shift};
664 } 664 }
665 665
666 # use like this: 666 # use like this:
667 timeslice { 667 timeslice {
668 # The following is an endless loop that would normally 668 # The following is an endless loop that would normally
669 # monopolise the process. Since it runs in a timesliced 669 # monopolise the process. Since it runs in a timesliced
670 # environment, it will regularly cede to other threads. 670 # environment, it will regularly cede to other threads.
671 while () { } 671 while () { }
672 }; 672 };
673 673
674 674
675=item killall 675=item killall
676 676
677Kills/terminates/cancels all coros except the currently running one. 677Kills/terminates/cancels all coros except the currently running one.
… …
793the thread is inside a C callback that doesn't expect to be canceled, 793the thread is inside a C callback that doesn't expect to be canceled,
794bad things can happen, or if the cancelled thread insists on running 794bad things can happen, or if the cancelled thread insists on running
795complicated cleanup handlers that rely on its thread context, things will 795complicated cleanup handlers that rely on its thread context, things will
796not work. 796not work.
797 797
798Any cleanup code being run (e.g. from C<guard> blocks) will be run without 798Any cleanup code being run (e.g. from C<guard> blocks, destructors and so
799a thread context, and is not allowed to switch to other threads. On the 799on) will be run without a thread context, and is not allowed to switch
800to other threads. A common mistake is to call C<< ->cancel >> from a
801destructor called by die'ing inside the thread to be cancelled for
802example.
803
800plus side, C<< ->cancel >> will always clean up the thread, no matter 804On the plus side, C<< ->cancel >> will always clean up the thread, no
801what. If your cleanup code is complex or you want to avoid cancelling a 805matter what. If your cleanup code is complex or you want to avoid
802C-thread that doesn't know how to clean up itself, it can be better to C<< 806cancelling a C-thread that doesn't know how to clean up itself, it can be
803->throw >> an exception, or use C<< ->safe_cancel >>. 807better to C<< ->throw >> an exception, or use C<< ->safe_cancel >>.
804 808
805The arguments to C<< ->cancel >> are not copied, but instead will 809The arguments to C<< ->cancel >> are not copied, but instead will
806be referenced directly (e.g. if you pass C<$var> and after the call 810be referenced directly (e.g. if you pass C<$var> and after the call
807change that variable, then you might change the return values passed to 811change that variable, then you might change the return values passed to
808e.g. C<join>, so don't do that). 812e.g. C<join>, so don't do that).
… …
814 818
815=item $coro->safe_cancel ($arg...) 819=item $coro->safe_cancel ($arg...)
816 820
817Works mostly like C<< ->cancel >>, but is inherently "safer", and 821Works mostly like C<< ->cancel >>, but is inherently "safer", and
818consequently, can fail with an exception in cases the thread is not in a 822consequently, can fail with an exception in cases the thread is not in a
819cancellable state. 823cancellable state. Essentially, C<< ->safe_cancel >> is a C<< ->cancel >>
824with extra checks before canceling.
820 825
821This method works a bit like throwing an exception that cannot be caught 826It works a bit like throwing an exception that cannot be caught -
822- specifically, it will clean up the thread from within itself, so 827specifically, it will clean up the thread from within itself, so all
823all cleanup handlers (e.g. C<guard> blocks) are run with full thread 828cleanup handlers (e.g. C<guard> blocks) are run with full thread
824context and can block if they wish. The downside is that there is no 829context and can block if they wish. The downside is that there is no
825guarantee that the thread can be cancelled when you call this method, and 830guarantee that the thread can be cancelled when you call this method, and
826therefore, it might fail. It is also considerably slower than C<cancel> or 831therefore, it might fail. It is also considerably slower than C<cancel> or
827C<terminate>. 832C<terminate>.
828 833
… …
1016otherwise you might suffer from crashes or worse. The only event library 1021otherwise you might suffer from crashes or worse. The only event library
1017currently known that is safe to use without C<unblock_sub> is L<EV> (but 1022currently known that is safe to use without C<unblock_sub> is L<EV> (but
1018you might still run into deadlocks if all event loops are blocked). 1023you might still run into deadlocks if all event loops are blocked).
1019 1024
1020Coro will try to catch you when you block in the event loop 1025Coro will try to catch you when you block in the event loop
1021("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and 1026("FATAL: $Coro::idle blocked itself"), but this is just best effort and
1022only works when you do not run your own event loop. 1027only works when you do not run your own event loop.
1023 1028
1024This function allows your callbacks to block by executing them in another 1029This function allows your callbacks to block by executing them in another
1025coro where it is safe to block. One example where blocking is handy 1030coro where it is safe to block. One example where blocking is handy
1026is when you use the L<Coro::AIO|Coro::AIO> functions to save results to 1031is when you use the L<Coro::AIO|Coro::AIO> functions to save results to
… …
1296 1301
1297XS API: L<Coro::MakeMaker>. 1302XS API: L<Coro::MakeMaker>.
1298 1303
1299Low level Configuration, Thread Environment, Continuations: L<Coro::State>. 1304Low level Configuration, Thread Environment, Continuations: L<Coro::State>.
1300 1305
1301=head1 AUTHOR 1306=head1 AUTHOR/SUPPORT/CONTACT
1302 1307
1303 Marc Lehmann <schmorp@schmorp.de> 1308 Marc A. Lehmann <schmorp@schmorp.de>
1304 http://home.schmorp.de/ 1309 http://software.schmorp.de/pkg/Coro.html
1305 1310
1306=cut 1311=cut
1307 1312

Diff Legend

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