| … | |
… | |
| 534 | # at this place, the timezone is Antarctica/South_Pole, |
534 | # at this place, the timezone is Antarctica/South_Pole, |
| 535 | # without disturbing the TZ of any other coro. |
535 | # without disturbing the TZ of any other coro. |
| 536 | }; |
536 | }; |
| 537 | |
537 | |
| 538 | This can be used to localise about any resource (locale, uid, |
538 | This can be used to localise about any resource (locale, uid, |
| 539 | current working directory etc.) to a block, despite the existance of |
539 | current working directory etc.) to a block, despite the existence of |
| 540 | other coros. |
540 | other coros. |
| 541 | |
541 | |
| 542 | Another interesting example implements time-sliced multitasking |
542 | Another interesting example implements time-sliced multitasking |
| 543 | using interval timers (this could obviously be optimised, but does |
543 | using interval timers (this could obviously be optimised, but does |
| 544 | the job): |
544 | the job): |
| … | |
… | |
| 626 | $state->is_new |
626 | $state->is_new |
| 627 | 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 |
| 628 | yet. Those states basically consist of only the code reference to |
628 | yet. Those states basically consist of only the code reference to |
| 629 | call and the arguments, but consumes very little other resources. |
629 | call and the arguments, but consumes very little other resources. |
| 630 | New states will automatically get assigned a perl interpreter when |
630 | New states will automatically get assigned a perl interpreter when |
| 631 | they are transfered to. |
631 | they are transferred to. |
| 632 | |
632 | |
| 633 | $state->is_zombie |
633 | $state->is_zombie |
| 634 | 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 |
| 635 | resources freed because they were "cancel"'ed, "terminate"'d, |
635 | resources freed because they were "cancel"'ed, "terminate"'d, |
| 636 | "safe_cancel"'ed or simply went out of scope. |
636 | "safe_cancel"'ed or simply went out of scope. |
| … | |
… | |
| 651 | |
651 | |
| 652 | $is_suspended = $coro->is_suspended |
652 | $is_suspended = $coro->is_suspended |
| 653 | Returns true iff this Coro object has been suspended. Suspended |
653 | Returns true iff this Coro object has been suspended. Suspended |
| 654 | Coros will not ever be scheduled. |
654 | Coros will not ever be scheduled. |
| 655 | |
655 | |
| 656 | $coro->cancel (arg...) |
656 | $coro->cancel ($arg...) |
| 657 | Terminates the given Coro thread and makes it return the given |
657 | Terminate the given Coro thread and make it return the given |
| 658 | arguments as status (default: an empty list). Never returns if the |
658 | arguments as status (default: an empty list). Never returns if the |
| 659 | Coro is the current Coro. |
659 | Coro is the current Coro. |
| 660 | |
660 | |
| 661 | 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 - |
| 662 | 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 |
| … | |
… | |
| 697 | 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 |
| 698 | guarantee that the thread can be cancelled when you call this |
698 | guarantee that the thread can be cancelled when you call this |
| 699 | method, and therefore, it might fail. It is also considerably slower |
699 | method, and therefore, it might fail. It is also considerably slower |
| 700 | than "cancel" or "terminate". |
700 | than "cancel" or "terminate". |
| 701 | |
701 | |
| 702 | 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 |
| 703 | 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. |
| 704 | |
706 | |
|
|
707 | The first two states are trivial - a thread that hasnot started or |
|
|
708 | has already finished is safe to cancel. |
|
|
709 | |
| 705 | The latter two basically mean that the thread isn't currently inside |
710 | The last state basically means that the thread isn't currently |
| 706 | 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 |
| 707 | modules) and isn't currently executing inside some C function itself |
712 | XS modules) and isn't currently executing inside some C function |
| 708 | (via Coro's XS API). |
713 | itself (via Coro's XS API). |
| 709 | |
714 | |
| 710 | 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 |
| 711 | 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 |
| 712 | return at all). |
717 | return at all). |
| 713 | |
718 | |
| … | |
… | |
| 907 | 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. |
| 908 | 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 |
| 909 | program, or when you use event-based libraries. |
914 | program, or when you use event-based libraries. |
| 910 | |
915 | |
| 911 | These typically register a callback for some event, and call that |
916 | These typically register a callback for some event, and call that |
| 912 | 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 |
| 913 | to just wait for the event, simplyifying things. |
918 | to just wait for the event, simplyifying things. |
| 914 | |
919 | |
| 915 | 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 |
| 916 | specific child has exited: |
921 | specific child has exited: |
| 917 | |
922 | |
| … | |
… | |
| 1036 | 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 |
| 1037 | can actually take advantage of custom hardware for this purpose (as |
1042 | can actually take advantage of custom hardware for this purpose (as |
| 1038 | 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, |
| 1039 | just much faster). |
1044 | just much faster). |
| 1040 | |
1045 | |
| 1041 | 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 |
| 1042 | structures between threads using copying semantics, which is very slow - |
1047 | structures between threads using copying semantics, which is very slow - |
| 1043 | 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 |
| 1044 | communication-intensive show extremely bad behaviour with i-threads (in |
1049 | communication-intensive show extremely bad behaviour with i-threads (in |
| 1045 | 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 |
| 1046 | 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 |
