… | |
… | |
366 | |
366 | |
367 | our $idle; # idle handler |
367 | our $idle; # idle handler |
368 | our $main; # main coro |
368 | our $main; # main coro |
369 | our $current; # current coro |
369 | our $current; # current coro |
370 | |
370 | |
371 | our $VERSION = 6.31; |
371 | our $VERSION = 6.41; |
372 | |
372 | |
373 | our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait); |
373 | our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait); |
374 | our %EXPORT_TAGS = ( |
374 | our %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 | |
677 | Kills/terminates/cancels all coros except the currently running one. |
677 | Kills/terminates/cancels all coros except the currently running one. |
… | |
… | |
793 | the thread is inside a C callback that doesn't expect to be canceled, |
793 | the thread is inside a C callback that doesn't expect to be canceled, |
794 | bad things can happen, or if the cancelled thread insists on running |
794 | bad things can happen, or if the cancelled thread insists on running |
795 | complicated cleanup handlers that rely on its thread context, things will |
795 | complicated cleanup handlers that rely on its thread context, things will |
796 | not work. |
796 | not work. |
797 | |
797 | |
798 | Any cleanup code being run (e.g. from C<guard> blocks) will be run without |
798 | Any cleanup code being run (e.g. from C<guard> blocks, destructors and so |
799 | a thread context, and is not allowed to switch to other threads. On the |
799 | on) will be run without a thread context, and is not allowed to switch |
|
|
800 | to other threads. A common mistake is to call C<< ->cancel >> from a |
|
|
801 | destructor called by die'ing inside the thread to be cancelled for |
|
|
802 | example. |
|
|
803 | |
800 | plus side, C<< ->cancel >> will always clean up the thread, no matter |
804 | On the plus side, C<< ->cancel >> will always clean up the thread, no |
801 | what. If your cleanup code is complex or you want to avoid cancelling a |
805 | matter what. If your cleanup code is complex or you want to avoid |
802 | C-thread that doesn't know how to clean up itself, it can be better to C<< |
806 | cancelling a C-thread that doesn't know how to clean up itself, it can be |
803 | ->throw >> an exception, or use C<< ->safe_cancel >>. |
807 | better to C<< ->throw >> an exception, or use C<< ->safe_cancel >>. |
804 | |
808 | |
805 | The arguments to C<< ->cancel >> are not copied, but instead will |
809 | The arguments to C<< ->cancel >> are not copied, but instead will |
806 | be referenced directly (e.g. if you pass C<$var> and after the call |
810 | be referenced directly (e.g. if you pass C<$var> and after the call |
807 | change that variable, then you might change the return values passed to |
811 | change that variable, then you might change the return values passed to |
808 | e.g. C<join>, so don't do that). |
812 | e.g. C<join>, so don't do that). |
… | |
… | |
814 | |
818 | |
815 | =item $coro->safe_cancel ($arg...) |
819 | =item $coro->safe_cancel ($arg...) |
816 | |
820 | |
817 | Works mostly like C<< ->cancel >>, but is inherently "safer", and |
821 | Works mostly like C<< ->cancel >>, but is inherently "safer", and |
818 | consequently, can fail with an exception in cases the thread is not in a |
822 | consequently, can fail with an exception in cases the thread is not in a |
819 | cancellable state. |
823 | cancellable state. Essentially, C<< ->safe_cancel >> is a C<< ->cancel >> |
|
|
824 | with extra checks before canceling. |
820 | |
825 | |
821 | This method works a bit like throwing an exception that cannot be caught |
826 | It works a bit like throwing an exception that cannot be caught - |
822 | - specifically, it will clean up the thread from within itself, so |
827 | specifically, it will clean up the thread from within itself, so all |
823 | all cleanup handlers (e.g. C<guard> blocks) are run with full thread |
828 | cleanup handlers (e.g. C<guard> blocks) are run with full thread |
824 | context and can block if they wish. The downside is that there is no |
829 | context and can block if they wish. The downside is that there is no |
825 | guarantee that the thread can be cancelled when you call this method, and |
830 | guarantee that the thread can be cancelled when you call this method, and |
826 | therefore, it might fail. It is also considerably slower than C<cancel> or |
831 | therefore, it might fail. It is also considerably slower than C<cancel> or |
827 | C<terminate>. |
832 | C<terminate>. |
828 | |
833 | |
… | |
… | |
914 | that is, after it's resources have been freed but before it is joined. The |
919 | that is, after it's resources have been freed but before it is joined. The |
915 | callback gets passed the terminate/cancel arguments, if any, and I<must |
920 | callback gets passed the terminate/cancel arguments, if any, and I<must |
916 | not> die, under any circumstances. |
921 | not> die, under any circumstances. |
917 | |
922 | |
918 | There can be any number of C<on_destroy> callbacks per coro, and there is |
923 | There can be any number of C<on_destroy> callbacks per coro, and there is |
919 | no way currently to remove a callback once added. |
924 | currently no way to remove a callback once added. |
920 | |
925 | |
921 | =item $oldprio = $coro->prio ($newprio) |
926 | =item $oldprio = $coro->prio ($newprio) |
922 | |
927 | |
923 | Sets (or gets, if the argument is missing) the priority of the |
928 | Sets (or gets, if the argument is missing) the priority of the |
924 | coro thread. Higher priority coro get run before lower priority |
929 | coro thread. Higher priority coro get run before lower priority |
… | |
… | |
1016 | otherwise you might suffer from crashes or worse. The only event library |
1021 | otherwise you might suffer from crashes or worse. The only event library |
1017 | currently known that is safe to use without C<unblock_sub> is L<EV> (but |
1022 | currently known that is safe to use without C<unblock_sub> is L<EV> (but |
1018 | you might still run into deadlocks if all event loops are blocked). |
1023 | you might still run into deadlocks if all event loops are blocked). |
1019 | |
1024 | |
1020 | Coro will try to catch you when you block in the event loop |
1025 | Coro 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 |
1022 | only works when you do not run your own event loop. |
1027 | only works when you do not run your own event loop. |
1023 | |
1028 | |
1024 | This function allows your callbacks to block by executing them in another |
1029 | This function allows your callbacks to block by executing them in another |
1025 | coro where it is safe to block. One example where blocking is handy |
1030 | coro where it is safe to block. One example where blocking is handy |
1026 | is when you use the L<Coro::AIO|Coro::AIO> functions to save results to |
1031 | is when you use the L<Coro::AIO|Coro::AIO> functions to save results to |