… | |
… | |
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 |
… | |
… | |
853 | otherwise you might suffer from crashes or worse. The only event |
857 | otherwise you might suffer from crashes or worse. The only event |
854 | library currently known that is safe to use without "unblock_sub" is |
858 | library currently known that is safe to use without "unblock_sub" is |
855 | EV (but you might still run into deadlocks if all event loops are |
859 | EV (but you might still run into deadlocks if all event loops are |
856 | blocked). |
860 | blocked). |
857 | |
861 | |
858 | Coro will try to catch you when you block in the event loop |
862 | Coro will try to catch you when you block in the event loop ("FATAL: |
859 | ("FATAL:$Coro::IDLE blocked itself"), but this is just best effort |
863 | $Coro::idle blocked itself"), but this is just best effort and only |
860 | and only works when you do not run your own event loop. |
864 | works when you do not run your own event loop. |
861 | |
865 | |
862 | This function allows your callbacks to block by executing them in |
866 | This function allows your callbacks to block by executing them in |
863 | another coro where it is safe to block. One example where blocking |
867 | another coro where it is safe to block. One example where blocking |
864 | is handy is when you use the Coro::AIO functions to save results to |
868 | is handy is when you use the Coro::AIO functions to save results to |
865 | disk, for example. |
869 | disk, for example. |
… | |
… | |
1070 | |
1074 | |
1071 | XS API: Coro::MakeMaker. |
1075 | XS API: Coro::MakeMaker. |
1072 | |
1076 | |
1073 | Low level Configuration, Thread Environment, Continuations: Coro::State. |
1077 | Low level Configuration, Thread Environment, Continuations: Coro::State. |
1074 | |
1078 | |
1075 | AUTHOR |
1079 | AUTHOR/SUPPORT/CONTACT |
1076 | Marc Lehmann <schmorp@schmorp.de> |
1080 | Marc A. Lehmann <schmorp@schmorp.de> |
1077 | http://home.schmorp.de/ |
1081 | http://software.schmorp.de/pkg/Coro.html |
1078 | |
1082 | |