… | |
… | |
66 | CORO THREAD LIFE CYCLE |
66 | CORO THREAD LIFE CYCLE |
67 | During the long and exciting (or not) life of a coro thread, it goes |
67 | During the long and exciting (or not) life of a coro thread, it goes |
68 | through a number of states: |
68 | through a number of states: |
69 | |
69 | |
70 | 1. Creation |
70 | 1. Creation |
71 | The first thing in the life of a coro thread is it's creation - |
71 | The first thing in the life of a coro thread is its creation - |
72 | obviously. The typical way to create a thread is to call the "async |
72 | obviously. The typical way to create a thread is to call the "async |
73 | BLOCK" function: |
73 | BLOCK" function: |
74 | |
74 | |
75 | async { |
75 | async { |
76 | # thread code goes here |
76 | # thread code goes here |
… | |
… | |
85 | This creates a new coro thread and puts it into the ready queue, |
85 | This creates a new coro thread and puts it into the ready queue, |
86 | meaning it will run as soon as the CPU is free for it. |
86 | meaning it will run as soon as the CPU is free for it. |
87 | |
87 | |
88 | "async" will return a Coro object - you can store this for future |
88 | "async" will return a Coro object - you can store this for future |
89 | reference or ignore it - a thread that is running, ready to run or |
89 | reference or ignore it - a thread that is running, ready to run or |
90 | waiting for some event is alive on it's own. |
90 | waiting for some event is alive on its own. |
91 | |
91 | |
92 | Another way to create a thread is to call the "new" constructor with |
92 | Another way to create a thread is to call the "new" constructor with |
93 | a code-reference: |
93 | a code-reference: |
94 | |
94 | |
95 | new Coro sub { |
95 | new Coro sub { |
… | |
… | |
239 | implements an endless loop, the $guard will not be cleaned up. |
239 | implements an endless loop, the $guard will not be cleaned up. |
240 | However, since the thread object returned by "async" is not stored |
240 | However, since the thread object returned by "async" is not stored |
241 | anywhere, the thread is initially referenced because it is in the |
241 | anywhere, the thread is initially referenced because it is in the |
242 | ready queue, when it runs it is referenced by $Coro::current, but |
242 | ready queue, when it runs it is referenced by $Coro::current, but |
243 | when it calls "schedule", it gets "cancel"ed causing the guard |
243 | when it calls "schedule", it gets "cancel"ed causing the guard |
244 | object to be destroyed (see the next section), and printing it's |
244 | object to be destroyed (see the next section), and printing its |
245 | message. |
245 | message. |
246 | |
246 | |
247 | If this seems a bit drastic, remember that this only happens when |
247 | If this seems a bit drastic, remember that this only happens when |
248 | nothing references the thread anymore, which means there is no way |
248 | nothing references the thread anymore, which means there is no way |
249 | to further execute it, ever. The only options at this point are |
249 | to further execute it, ever. The only options at this point are |
… | |
… | |
252 | 5. Cleanup |
252 | 5. Cleanup |
253 | Threads will allocate various resources. Most but not all will be |
253 | Threads will allocate various resources. Most but not all will be |
254 | returned when a thread terminates, during clean-up. |
254 | returned when a thread terminates, during clean-up. |
255 | |
255 | |
256 | Cleanup is quite similar to throwing an uncaught exception: perl |
256 | Cleanup is quite similar to throwing an uncaught exception: perl |
257 | will work it's way up through all subroutine calls and blocks. On |
257 | will work its way up through all subroutine calls and blocks. On its |
258 | it's way, it will release all "my" variables, undo all "local"'s and |
258 | way, it will release all "my" variables, undo all "local"'s and free |
259 | free any other resources truly local to the thread. |
259 | any other resources truly local to the thread. |
260 | |
260 | |
261 | So, a common way to free resources is to keep them referenced only |
261 | So, a common way to free resources is to keep them referenced only |
262 | by my variables: |
262 | by my variables: |
263 | |
263 | |
264 | async { |
264 | async { |
… | |
… | |
284 | those code blocks): |
284 | those code blocks): |
285 | |
285 | |
286 | async { |
286 | async { |
287 | my $window = new Gtk2::Window "toplevel"; |
287 | my $window = new Gtk2::Window "toplevel"; |
288 | # The window will not be cleaned up automatically, even when $window |
288 | # The window will not be cleaned up automatically, even when $window |
289 | # gets freed, so use a guard to ensure it's destruction |
289 | # gets freed, so use a guard to ensure its destruction |
290 | # in case of an error: |
290 | # in case of an error: |
291 | my $window_guard = Guard::guard { $window->destroy }; |
291 | my $window_guard = Guard::guard { $window->destroy }; |
292 | |
292 | |
293 | # we are safe here |
293 | # we are safe here |
294 | }; |
294 | }; |
… | |
… | |
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. its |
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. |
636 | |
637 | |
637 | The name "zombie" stems from UNIX culture, where a process that has |
638 | The name "zombie" stems from UNIX culture, where a process that has |
638 | exited and only stores and exit status and no other resources is |
639 | exited and only stores and exit status and no other resources is |
… | |
… | |
650 | |
651 | |
651 | $is_suspended = $coro->is_suspended |
652 | $is_suspended = $coro->is_suspended |
652 | Returns true iff this Coro object has been suspended. Suspended |
653 | Returns true iff this Coro object has been suspended. Suspended |
653 | Coros will not ever be scheduled. |
654 | Coros will not ever be scheduled. |
654 | |
655 | |
655 | $coro->cancel (arg...) |
656 | $coro->cancel ($arg...) |
656 | Terminates the given Coro thread and makes it return the given |
657 | Terminate the given Coro thread and make it return the given |
657 | arguments as status (default: an empty list). Never returns if the |
658 | arguments as status (default: an empty list). Never returns if the |
658 | Coro is the current Coro. |
659 | Coro is the current Coro. |
659 | |
660 | |
660 | This is a rather brutal way to free a coro, with some limitations - |
661 | This is a rather brutal way to free a coro, with some limitations - |
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 |
… | |
… | |
696 | context and can block if they wish. The downside is that there is no |
697 | context and can block if they wish. The downside is that there is no |
697 | guarantee that the thread can be cancelled when you call this |
698 | guarantee that the thread can be cancelled when you call this |
698 | method, and therefore, it might fail. It is also considerably slower |
699 | method, and therefore, it might fail. It is also considerably slower |
699 | than "cancel" or "terminate". |
700 | than "cancel" or "terminate". |
700 | |
701 | |
701 | 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 has never been |
|
|
703 | run yet, has already been canceled/terminated or otherwise |
702 | yet, or it has no C context attached and is inside an SLF function. |
704 | destroyed, or has no C context attached and is inside an SLF |
|
|
705 | function. |
703 | |
706 | |
|
|
707 | The first two states are trivial - a thread that hasnot started or |
|
|
708 | has already finished is safe to cancel. |
|
|
709 | |
704 | The latter two basically mean that the thread isn't currently inside |
710 | The last state basically means that the thread isn't currently |
705 | a perl callback called from some C function (usually via some XS |
711 | inside a perl callback called from some C function (usually via some |
706 | modules) and isn't currently executing inside some C function itself |
712 | XS modules) and isn't currently executing inside some C function |
707 | (via Coro's XS API). |
713 | itself (via Coro's XS API). |
708 | |
714 | |
709 | This call returns true when it could cancel the thread, or croaks |
715 | This call returns true when it could cancel the thread, or croaks |
710 | with an error otherwise (i.e. it either returns true or doesn't |
716 | with an error otherwise (i.e. it either returns true or doesn't |
711 | return at all). |
717 | return at all). |
712 | |
718 | |
… | |
… | |
777 | from multiple threads, and all will be resumed and given the status |
783 | from multiple threads, and all will be resumed and given the status |
778 | return once the $coro terminates. |
784 | return once the $coro terminates. |
779 | |
785 | |
780 | $coro->on_destroy (\&cb) |
786 | $coro->on_destroy (\&cb) |
781 | Registers a callback that is called when this coro thread gets |
787 | Registers a callback that is called when this coro thread gets |
782 | destroyed, that is, after it's resources have been freed but before |
788 | destroyed, that is, after its resources have been freed but before |
783 | it is joined. The callback gets passed the terminate/cancel |
789 | it is joined. The callback gets passed the terminate/cancel |
784 | arguments, if any, and *must not* die, under any circumstances. |
790 | arguments, if any, and *must not* die, under any circumstances. |
785 | |
791 | |
786 | There can be any number of "on_destroy" callbacks per coro, and |
792 | There can be any number of "on_destroy" callbacks per coro, and |
787 | there is currently no way to remove a callback once added. |
793 | there is currently no way to remove a callback once added. |
… | |
… | |
906 | It is very common for a coro to wait for some callback to be called. |
912 | It is very common for a coro to wait for some callback to be called. |
907 | This occurs naturally when you use coro in an otherwise event-based |
913 | This occurs naturally when you use coro in an otherwise event-based |
908 | program, or when you use event-based libraries. |
914 | program, or when you use event-based libraries. |
909 | |
915 | |
910 | These typically register a callback for some event, and call that |
916 | These typically register a callback for some event, and call that |
911 | callback when the event occured. In a coro, however, you typically want |
917 | callback when the event occurred. In a coro, however, you typically want |
912 | to just wait for the event, simplyifying things. |
918 | to just wait for the event, simplyifying things. |
913 | |
919 | |
914 | For example "AnyEvent->child" registers a callback to be called when a |
920 | For example "AnyEvent->child" registers a callback to be called when a |
915 | specific child has exited: |
921 | specific child has exited: |
916 | |
922 | |
… | |
… | |
1035 | processes. What makes it so bad is that on non-windows platforms, you |
1041 | processes. What makes it so bad is that on non-windows platforms, you |
1036 | can actually take advantage of custom hardware for this purpose (as |
1042 | can actually take advantage of custom hardware for this purpose (as |
1037 | evidenced by the forks module, which gives you the (i-) threads API, |
1043 | evidenced by the forks module, which gives you the (i-) threads API, |
1038 | just much faster). |
1044 | just much faster). |
1039 | |
1045 | |
1040 | Sharing data is in the i-threads model is done by transfering data |
1046 | Sharing data is in the i-threads model is done by transferring data |
1041 | structures between threads using copying semantics, which is very slow - |
1047 | structures between threads using copying semantics, which is very slow - |
1042 | shared data simply does not exist. Benchmarks using i-threads which are |
1048 | shared data simply does not exist. Benchmarks using i-threads which are |
1043 | communication-intensive show extremely bad behaviour with i-threads (in |
1049 | communication-intensive show extremely bad behaviour with i-threads (in |
1044 | fact, so bad that Coro, which cannot take direct advantage of multiple |
1050 | fact, so bad that Coro, which cannot take direct advantage of multiple |
1045 | CPUs, is often orders of magnitude faster because it shares data using |
1051 | CPUs, is often orders of magnitude faster because it shares data using |
… | |
… | |
1074 | |
1080 | |
1075 | XS API: Coro::MakeMaker. |
1081 | XS API: Coro::MakeMaker. |
1076 | |
1082 | |
1077 | Low level Configuration, Thread Environment, Continuations: Coro::State. |
1083 | Low level Configuration, Thread Environment, Continuations: Coro::State. |
1078 | |
1084 | |
1079 | AUTHOR |
1085 | AUTHOR/SUPPORT/CONTACT |
1080 | Marc Lehmann <schmorp@schmorp.de> |
1086 | Marc A. Lehmann <schmorp@schmorp.de> |
1081 | http://home.schmorp.de/ |
1087 | http://software.schmorp.de/pkg/Coro.html |
1082 | |
1088 | |