| … | |
… | |
| 549 | Coro::on_enter { |
549 | Coro::on_enter { |
| 550 | # on entering the thread, we set an VTALRM handler to cede |
550 | # on entering the thread, we set an VTALRM handler to cede |
| 551 | $SIG{VTALRM} = sub { cede }; |
551 | $SIG{VTALRM} = sub { cede }; |
| 552 | # and then start the interval timer |
552 | # and then start the interval timer |
| 553 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01; |
553 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01; |
| 554 | }; |
554 | }; |
| 555 | Coro::on_leave { |
555 | Coro::on_leave { |
| 556 | # on leaving the thread, we stop the interval timer again |
556 | # on leaving the thread, we stop the interval timer again |
| 557 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0; |
557 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0; |
| 558 | }; |
558 | }; |
| 559 | |
559 | |
| 560 | &{+shift}; |
560 | &{+shift}; |
| 561 | } |
561 | } |
| 562 | |
562 | |
| 563 | # use like this: |
563 | # use like this: |
| 564 | timeslice { |
564 | timeslice { |
| 565 | # The following is an endless loop that would normally |
565 | # The following is an endless loop that would normally |
| 566 | # monopolise the process. Since it runs in a timesliced |
566 | # monopolise the process. Since it runs in a timesliced |
| … | |
… | |
| 661 | if the thread is inside a C callback that doesn't expect to be |
661 | if the thread is inside a C callback that doesn't expect to be |
| 662 | canceled, bad things can happen, or if the cancelled thread insists |
662 | canceled, bad things can happen, or if the cancelled thread insists |
| 663 | on running complicated cleanup handlers that rely on its thread |
663 | on running complicated cleanup handlers that rely on its thread |
| 664 | context, things will not work. |
664 | context, things will not work. |
| 665 | |
665 | |
| 666 | Any cleanup code being run (e.g. from "guard" blocks) will be run |
666 | Any cleanup code being run (e.g. from "guard" blocks, destructors |
| 667 | without a thread context, and is not allowed to switch to other |
667 | and so on) will be run without a thread context, and is not allowed |
|
|
668 | to switch to other threads. A common mistake is to call "->cancel" |
|
|
669 | from a destructor called by die'ing inside the thread to be |
|
|
670 | cancelled for example. |
|
|
671 | |
| 668 | threads. On the plus side, "->cancel" will always clean up the |
672 | On the plus side, "->cancel" will always clean up the thread, no |
| 669 | thread, no matter what. If your cleanup code is complex or you want |
673 | matter what. If your cleanup code is complex or you want to avoid |
| 670 | to avoid cancelling a C-thread that doesn't know how to clean up |
674 | cancelling a C-thread that doesn't know how to clean up itself, it |
| 671 | itself, it can be better to "->throw" an exception, or use |
675 | can be better to "->throw" an exception, or use "->safe_cancel". |
| 672 | "->safe_cancel". |
|
|
| 673 | |
676 | |
| 674 | The arguments to "->cancel" are not copied, but instead will be |
677 | The arguments to "->cancel" are not copied, but instead will be |
| 675 | referenced directly (e.g. if you pass $var and after the call change |
678 | referenced directly (e.g. if you pass $var and after the call change |
| 676 | that variable, then you might change the return values passed to |
679 | that variable, then you might change the return values passed to |
| 677 | e.g. "join", so don't do that). |
680 | e.g. "join", so don't do that). |
| … | |
… | |
| 682 | actually destruct the Coro object. |
685 | actually destruct the Coro object. |
| 683 | |
686 | |
| 684 | $coro->safe_cancel ($arg...) |
687 | $coro->safe_cancel ($arg...) |
| 685 | Works mostly like "->cancel", but is inherently "safer", and |
688 | Works mostly like "->cancel", but is inherently "safer", and |
| 686 | consequently, can fail with an exception in cases the thread is not |
689 | consequently, can fail with an exception in cases the thread is not |
| 687 | in a cancellable state. |
690 | in a cancellable state. Essentially, "->safe_cancel" is a "->cancel" |
|
|
691 | with extra checks before canceling. |
| 688 | |
692 | |
| 689 | This method works a bit like throwing an exception that cannot be |
693 | It works a bit like throwing an exception that cannot be caught - |
| 690 | caught - specifically, it will clean up the thread from within |
694 | specifically, it will clean up the thread from within itself, so all |
| 691 | itself, so all cleanup handlers (e.g. "guard" blocks) are run with |
695 | cleanup handlers (e.g. "guard" blocks) are run with full thread |
| 692 | full thread context and can block if they wish. The downside is that |
696 | context and can block if they wish. The downside is that there is no |
| 693 | there is no guarantee that the thread can be cancelled when you call |
697 | guarantee that the thread can be cancelled when you call this |
| 694 | this method, and therefore, it might fail. It is also considerably |
698 | method, and therefore, it might fail. It is also considerably slower |
| 695 | slower than "cancel" or "terminate". |
699 | than "cancel" or "terminate". |
| 696 | |
700 | |
| 697 | A thread is in a safe-cancellable state if it either hasn't been run |
701 | A thread is in a safe-cancellable state if it either hasn't been run |
| 698 | yet, or it has no C context attached and is inside an SLF function. |
702 | yet, or it has no C context attached and is inside an SLF function. |
| 699 | |
703 | |
| 700 | The latter two basically mean that the thread isn't currently inside |
704 | The latter two basically mean that the thread isn't currently inside |
| … | |
… | |
| 778 | destroyed, that is, after it's resources have been freed but before |
782 | destroyed, that is, after it's resources have been freed but before |
| 779 | it is joined. The callback gets passed the terminate/cancel |
783 | it is joined. The callback gets passed the terminate/cancel |
| 780 | arguments, if any, and *must not* die, under any circumstances. |
784 | arguments, if any, and *must not* die, under any circumstances. |
| 781 | |
785 | |
| 782 | There can be any number of "on_destroy" callbacks per coro, and |
786 | There can be any number of "on_destroy" callbacks per coro, and |
| 783 | there is no way currently to remove a callback once added. |
787 | there is currently no way to remove a callback once added. |
| 784 | |
788 | |
| 785 | $oldprio = $coro->prio ($newprio) |
789 | $oldprio = $coro->prio ($newprio) |
| 786 | Sets (or gets, if the argument is missing) the priority of the coro |
790 | Sets (or gets, if the argument is missing) the priority of the coro |
| 787 | thread. Higher priority coro get run before lower priority coros. |
791 | thread. Higher priority coro get run before lower priority coros. |
| 788 | Priorities are small signed integers (currently -4 .. +3), that you |
792 | Priorities are small signed integers (currently -4 .. +3), that you |
