| … | |
… | |
| 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 | |
