… | |
… | |
417 | program, as "async" does. As the coro is being reused, stuff like |
417 | program, as "async" does. As the coro is being reused, stuff like |
418 | "on_destroy" will not work in the expected way, unless you call |
418 | "on_destroy" will not work in the expected way, unless you call |
419 | terminate or cancel, which somehow defeats the purpose of pooling |
419 | terminate or cancel, which somehow defeats the purpose of pooling |
420 | (but is fine in the exceptional case). |
420 | (but is fine in the exceptional case). |
421 | |
421 | |
422 | The priority will be reset to 0 after each run, tracing will be |
422 | The priority will be reset to 0 after each run, all "swap_sv" calls |
423 | disabled, the description will be reset and the default output |
423 | will be undone, tracing will be disabled, the description will be |
424 | filehandle gets restored, so you can change all these. Otherwise the |
424 | reset and the default output filehandle gets restored, so you can |
425 | coro will be re-used "as-is": most notably if you change other |
425 | change all these. Otherwise the coro will be re-used "as-is": most |
426 | per-coro global stuff such as $/ you *must needs* revert that |
426 | notably if you change other per-coro global stuff such as $/ you |
427 | change, which is most simply done by using local as in: "local $/". |
427 | *must needs* revert that change, which is most simply done by using |
|
|
428 | local as in: "local $/". |
428 | |
429 | |
429 | The idle pool size is limited to 8 idle coros (this can be adjusted |
430 | The idle pool size is limited to 8 idle coros (this can be adjusted |
430 | by changing $Coro::POOL_SIZE), but there can be as many non-idle |
431 | by changing $Coro::POOL_SIZE), but there can be as many non-idle |
431 | coros as required. |
432 | coros as required. |
432 | |
433 | |
… | |
… | |
533 | # at this place, the timezone is Antarctica/South_Pole, |
534 | # at this place, the timezone is Antarctica/South_Pole, |
534 | # without disturbing the TZ of any other coro. |
535 | # without disturbing the TZ of any other coro. |
535 | }; |
536 | }; |
536 | |
537 | |
537 | This can be used to localise about any resource (locale, uid, |
538 | This can be used to localise about any resource (locale, uid, |
538 | current working directory etc.) to a block, despite the existance of |
539 | current working directory etc.) to a block, despite the existence of |
539 | other coros. |
540 | other coros. |
540 | |
541 | |
541 | Another interesting example implements time-sliced multitasking |
542 | Another interesting example implements time-sliced multitasking |
542 | using interval timers (this could obviously be optimised, but does |
543 | using interval timers (this could obviously be optimised, but does |
543 | the job): |
544 | the job): |
… | |
… | |
625 | $state->is_new |
626 | $state->is_new |
626 | Returns true iff this Coro object is "new", i.e. has never been run |
627 | Returns true iff this Coro object is "new", i.e. has never been run |
627 | yet. Those states basically consist of only the code reference to |
628 | yet. Those states basically consist of only the code reference to |
628 | call and the arguments, but consumes very little other resources. |
629 | call and the arguments, but consumes very little other resources. |
629 | New states will automatically get assigned a perl interpreter when |
630 | New states will automatically get assigned a perl interpreter when |
630 | they are transfered to. |
631 | they are transferred to. |
631 | |
632 | |
632 | $state->is_zombie |
633 | $state->is_zombie |
633 | Returns true iff the Coro object has been cancelled, i.e. it's |
634 | Returns true iff the Coro object has been cancelled, i.e. it's |
634 | resources freed because they were "cancel"'ed, "terminate"'d, |
635 | resources freed because they were "cancel"'ed, "terminate"'d, |
635 | "safe_cancel"'ed or simply went out of scope. |
636 | "safe_cancel"'ed or simply went out of scope. |
… | |
… | |
661 | if the thread is inside a C callback that doesn't expect to be |
662 | 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 |
663 | canceled, bad things can happen, or if the cancelled thread insists |
663 | on running complicated cleanup handlers that rely on its thread |
664 | on running complicated cleanup handlers that rely on its thread |
664 | context, things will not work. |
665 | context, things will not work. |
665 | |
666 | |
666 | Any cleanup code being run (e.g. from "guard" blocks) will be run |
667 | Any cleanup code being run (e.g. from "guard" blocks, destructors |
667 | without a thread context, and is not allowed to switch to other |
668 | and so on) will be run without a thread context, and is not allowed |
|
|
669 | to switch to other threads. A common mistake is to call "->cancel" |
|
|
670 | from a destructor called by die'ing inside the thread to be |
|
|
671 | cancelled for example. |
|
|
672 | |
668 | threads. On the plus side, "->cancel" will always clean up the |
673 | 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 |
674 | 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 |
675 | 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 |
676 | can be better to "->throw" an exception, or use "->safe_cancel". |
672 | "->safe_cancel". |
|
|
673 | |
677 | |
674 | The arguments to "->cancel" are not copied, but instead will be |
678 | 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 |
679 | 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 |
680 | that variable, then you might change the return values passed to |
677 | e.g. "join", so don't do that). |
681 | e.g. "join", so don't do that). |
… | |
… | |
682 | actually destruct the Coro object. |
686 | actually destruct the Coro object. |
683 | |
687 | |
684 | $coro->safe_cancel ($arg...) |
688 | $coro->safe_cancel ($arg...) |
685 | Works mostly like "->cancel", but is inherently "safer", and |
689 | Works mostly like "->cancel", but is inherently "safer", and |
686 | consequently, can fail with an exception in cases the thread is not |
690 | consequently, can fail with an exception in cases the thread is not |
687 | in a cancellable state. |
691 | in a cancellable state. Essentially, "->safe_cancel" is a "->cancel" |
|
|
692 | with extra checks before canceling. |
688 | |
693 | |
689 | This method works a bit like throwing an exception that cannot be |
694 | It works a bit like throwing an exception that cannot be caught - |
690 | caught - specifically, it will clean up the thread from within |
695 | 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 |
696 | 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 |
697 | 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 |
698 | guarantee that the thread can be cancelled when you call this |
694 | this method, and therefore, it might fail. It is also considerably |
699 | method, and therefore, it might fail. It is also considerably slower |
695 | slower than "cancel" or "terminate". |
700 | than "cancel" or "terminate". |
696 | |
701 | |
697 | A thread is in a safe-cancellable state if it either hasn't been run |
702 | 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. |
703 | yet, or it has no C context attached and is inside an SLF function. |
699 | |
704 | |
700 | The latter two basically mean that the thread isn't currently inside |
705 | The latter two basically mean that the thread isn't currently inside |
… | |
… | |
853 | otherwise you might suffer from crashes or worse. The only event |
858 | otherwise you might suffer from crashes or worse. The only event |
854 | library currently known that is safe to use without "unblock_sub" is |
859 | 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 |
860 | EV (but you might still run into deadlocks if all event loops are |
856 | blocked). |
861 | blocked). |
857 | |
862 | |
858 | Coro will try to catch you when you block in the event loop |
863 | 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 |
864 | $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. |
865 | works when you do not run your own event loop. |
861 | |
866 | |
862 | This function allows your callbacks to block by executing them in |
867 | This function allows your callbacks to block by executing them in |
863 | another coro where it is safe to block. One example where blocking |
868 | 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 |
869 | is handy is when you use the Coro::AIO functions to save results to |
865 | disk, for example. |
870 | disk, for example. |
… | |
… | |
902 | It is very common for a coro to wait for some callback to be called. |
907 | It is very common for a coro to wait for some callback to be called. |
903 | This occurs naturally when you use coro in an otherwise event-based |
908 | This occurs naturally when you use coro in an otherwise event-based |
904 | program, or when you use event-based libraries. |
909 | program, or when you use event-based libraries. |
905 | |
910 | |
906 | These typically register a callback for some event, and call that |
911 | These typically register a callback for some event, and call that |
907 | callback when the event occured. In a coro, however, you typically want |
912 | callback when the event occurred. In a coro, however, you typically want |
908 | to just wait for the event, simplyifying things. |
913 | to just wait for the event, simplyifying things. |
909 | |
914 | |
910 | For example "AnyEvent->child" registers a callback to be called when a |
915 | For example "AnyEvent->child" registers a callback to be called when a |
911 | specific child has exited: |
916 | specific child has exited: |
912 | |
917 | |
… | |
… | |
1031 | processes. What makes it so bad is that on non-windows platforms, you |
1036 | processes. What makes it so bad is that on non-windows platforms, you |
1032 | can actually take advantage of custom hardware for this purpose (as |
1037 | can actually take advantage of custom hardware for this purpose (as |
1033 | evidenced by the forks module, which gives you the (i-) threads API, |
1038 | evidenced by the forks module, which gives you the (i-) threads API, |
1034 | just much faster). |
1039 | just much faster). |
1035 | |
1040 | |
1036 | Sharing data is in the i-threads model is done by transfering data |
1041 | Sharing data is in the i-threads model is done by transferring data |
1037 | structures between threads using copying semantics, which is very slow - |
1042 | structures between threads using copying semantics, which is very slow - |
1038 | shared data simply does not exist. Benchmarks using i-threads which are |
1043 | shared data simply does not exist. Benchmarks using i-threads which are |
1039 | communication-intensive show extremely bad behaviour with i-threads (in |
1044 | communication-intensive show extremely bad behaviour with i-threads (in |
1040 | fact, so bad that Coro, which cannot take direct advantage of multiple |
1045 | fact, so bad that Coro, which cannot take direct advantage of multiple |
1041 | CPUs, is often orders of magnitude faster because it shares data using |
1046 | CPUs, is often orders of magnitude faster because it shares data using |
… | |
… | |
1070 | |
1075 | |
1071 | XS API: Coro::MakeMaker. |
1076 | XS API: Coro::MakeMaker. |
1072 | |
1077 | |
1073 | Low level Configuration, Thread Environment, Continuations: Coro::State. |
1078 | Low level Configuration, Thread Environment, Continuations: Coro::State. |
1074 | |
1079 | |
1075 | AUTHOR |
1080 | AUTHOR/SUPPORT/CONTACT |
1076 | Marc Lehmann <schmorp@schmorp.de> |
1081 | Marc A. Lehmann <schmorp@schmorp.de> |
1077 | http://home.schmorp.de/ |
1082 | http://software.schmorp.de/pkg/Coro.html |
1078 | |
1083 | |