… | |
… | |
186 | |
186 | |
187 | async { |
187 | async { |
188 | Coro::terminate "return value 1", "return value 2"; |
188 | Coro::terminate "return value 1", "return value 2"; |
189 | }; |
189 | }; |
190 | |
190 | |
191 | And yet another way is to "->cancel" (or "->safe_cancel") the coro |
191 | Yet another way is to "->cancel" (or "->safe_cancel") the coro |
192 | thread from another thread: |
192 | thread from another thread: |
193 | |
193 | |
194 | my $coro = async { |
194 | my $coro = async { |
195 | exit 1; |
195 | exit 1; |
196 | }; |
196 | }; |
… | |
… | |
209 | So, cancelling a thread that runs in an XS event loop might not be |
209 | So, cancelling a thread that runs in an XS event loop might not be |
210 | the best idea, but any other combination that deals with perl only |
210 | the best idea, but any other combination that deals with perl only |
211 | (cancelling when a thread is in a "tie" method or an "AUTOLOAD" for |
211 | (cancelling when a thread is in a "tie" method or an "AUTOLOAD" for |
212 | example) is safe. |
212 | example) is safe. |
213 | |
213 | |
214 | Lastly, a coro thread object that isn't referenced is "->cancel"'ed |
214 | Last not least, a coro thread object that isn't referenced is |
215 | automatically - just like other objects in Perl. This is not such a |
215 | "->cancel"'ed automatically - just like other objects in Perl. This |
216 | common case, however - a running thread is referencedy b |
216 | is not such a common case, however - a running thread is referencedy |
217 | $Coro::current, a thread ready to run is referenced by the ready |
217 | by $Coro::current, a thread ready to run is referenced by the ready |
218 | queue, a thread waiting on a lock or semaphore is referenced by |
218 | queue, a thread waiting on a lock or semaphore is referenced by |
219 | being in some wait list and so on. But a thread that isn't in any of |
219 | being in some wait list and so on. But a thread that isn't in any of |
220 | those queues gets cancelled: |
220 | those queues gets cancelled: |
221 | |
221 | |
222 | async { |
222 | async { |
223 | schedule; # cede to other coros, don't go into the ready queue |
223 | schedule; # cede to other coros, don't go into the ready queue |
224 | }; |
224 | }; |
225 | |
225 | |
226 | cede; |
226 | cede; |
227 | # now the async above is destroyed, as it is not referenced by anything. |
227 | # now the async above is destroyed, as it is not referenced by anything. |
|
|
228 | |
|
|
229 | A slightly embellished example might make it clearer: |
|
|
230 | |
|
|
231 | async { |
|
|
232 | my $guard = Guard::guard { print "destroyed\n" }; |
|
|
233 | schedule while 1; |
|
|
234 | }; |
|
|
235 | |
|
|
236 | cede; |
|
|
237 | |
|
|
238 | Superficially one might not expect any output - since the "async" |
|
|
239 | implements an endless loop, the $guard will not be cleaned up. |
|
|
240 | However, since the thread object returned by "async" is not stored |
|
|
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 |
|
|
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 |
|
|
245 | message. |
|
|
246 | |
|
|
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 |
|
|
249 | to further execute it, ever. The only options at this point are |
|
|
250 | leaking the thread, or cleaning it up, which brings us to... |
228 | |
251 | |
229 | 5. Cleanup |
252 | 5. Cleanup |
230 | Threads will allocate various resources. Most but not all will be |
253 | Threads will allocate various resources. Most but not all will be |
231 | returned when a thread terminates, during clean-up. |
254 | returned when a thread terminates, during clean-up. |
232 | |
255 | |
… | |
… | |
250 | |
273 | |
251 | my $sem = new Coro::Semaphore; |
274 | my $sem = new Coro::Semaphore; |
252 | |
275 | |
253 | async { |
276 | async { |
254 | my $lock_guard = $sem->guard; |
277 | my $lock_guard = $sem->guard; |
255 | # if we reutrn, or die or get cancelled, here, |
278 | # if we return, or die or get cancelled, here, |
256 | # then the semaphore will be "up"ed. |
279 | # then the semaphore will be "up"ed. |
257 | }; |
280 | }; |
258 | |
281 | |
259 | The "Guard::guard" function comes in handy for any custom cleanup |
282 | The "Guard::guard" function comes in handy for any custom cleanup |
260 | you might want to do (but you cannot switch to other coroutines form |
283 | you might want to do (but you cannot switch to other coroutines from |
261 | those code blocks): |
284 | those code blocks): |
262 | |
285 | |
263 | async { |
286 | async { |
264 | my $window = new Gtk2::Window "toplevel"; |
287 | my $window = new Gtk2::Window "toplevel"; |
265 | # The window will not be cleaned up automatically, even when $window |
288 | # The window will not be cleaned up automatically, even when $window |
… | |
… | |
282 | 6. Viva La Zombie Muerte |
305 | 6. Viva La Zombie Muerte |
283 | Even after a thread has terminated and cleaned up its resources, the |
306 | Even after a thread has terminated and cleaned up its resources, the |
284 | Coro object still is there and stores the return values of the |
307 | Coro object still is there and stores the return values of the |
285 | thread. |
308 | thread. |
286 | |
309 | |
287 | The means the Coro object gets freed automatically when the thread |
310 | When there are no other references, it will simply be cleaned up and |
288 | has terminated and cleaned up and there arenot other references. |
311 | freed. |
289 | |
312 | |
290 | If there are, the Coro object will stay around, and you can call |
313 | If there areany references, the Coro object will stay around, and |
291 | "->join" as many times as you wish to retrieve the result values: |
314 | you can call "->join" as many times as you wish to retrieve the |
|
|
315 | result values: |
292 | |
316 | |
293 | async { |
317 | async { |
294 | print "hi\n"; |
318 | print "hi\n"; |
295 | 1 |
319 | 1 |
296 | }; |
320 | }; |
… | |
… | |
316 | }; |
340 | }; |
317 | |
341 | |
318 | GLOBAL VARIABLES |
342 | GLOBAL VARIABLES |
319 | $Coro::main |
343 | $Coro::main |
320 | This variable stores the Coro object that represents the main |
344 | This variable stores the Coro object that represents the main |
321 | program. While you cna "ready" it and do most other things you can |
345 | program. While you can "ready" it and do most other things you can |
322 | do to coro, it is mainly useful to compare again $Coro::current, to |
346 | do to coro, it is mainly useful to compare again $Coro::current, to |
323 | see whether you are running in the main program or not. |
347 | see whether you are running in the main program or not. |
324 | |
348 | |
325 | $Coro::current |
349 | $Coro::current |
326 | The Coro object representing the current coro (the last coro that |
350 | The Coro object representing the current coro (the last coro that |
… | |
… | |
525 | Coro::on_enter { |
549 | Coro::on_enter { |
526 | # on entering the thread, we set an VTALRM handler to cede |
550 | # on entering the thread, we set an VTALRM handler to cede |
527 | $SIG{VTALRM} = sub { cede }; |
551 | $SIG{VTALRM} = sub { cede }; |
528 | # and then start the interval timer |
552 | # and then start the interval timer |
529 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01; |
553 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01; |
530 | }; |
554 | }; |
531 | Coro::on_leave { |
555 | Coro::on_leave { |
532 | # on leaving the thread, we stop the interval timer again |
556 | # on leaving the thread, we stop the interval timer again |
533 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0; |
557 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0; |
534 | }; |
558 | }; |
535 | |
559 | |
536 | &{+shift}; |
560 | &{+shift}; |
537 | } |
561 | } |
538 | |
562 | |
539 | # use like this: |
563 | # use like this: |
540 | timeslice { |
564 | timeslice { |
541 | # The following is an endless loop that would normally |
565 | # The following is an endless loop that would normally |
542 | # monopolise the process. Since it runs in a timesliced |
566 | # monopolise the process. Since it runs in a timesliced |
… | |
… | |
637 | 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 |
638 | canceled, bad things can happen, or if the cancelled thread insists |
662 | canceled, bad things can happen, or if the cancelled thread insists |
639 | on running complicated cleanup handlers that rely on its thread |
663 | on running complicated cleanup handlers that rely on its thread |
640 | context, things will not work. |
664 | context, things will not work. |
641 | |
665 | |
642 | 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 |
643 | 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 | |
644 | threads. On the plus side, "->cancel" will always clean up the |
672 | On the plus side, "->cancel" will always clean up the thread, no |
645 | 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 |
646 | 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 |
647 | itself, it can be better to "->throw" an exception, or use |
675 | can be better to "->throw" an exception, or use "->safe_cancel". |
648 | "->safe_cancel". |
|
|
649 | |
676 | |
650 | The arguments to "->cancel" are not copied, but instead will be |
677 | The arguments to "->cancel" are not copied, but instead will be |
651 | 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 |
652 | that variable, then you might change the return values passed to |
679 | that variable, then you might change the return values passed to |
653 | e.g. "join", so don't do that). |
680 | e.g. "join", so don't do that). |
… | |
… | |
658 | actually destruct the Coro object. |
685 | actually destruct the Coro object. |
659 | |
686 | |
660 | $coro->safe_cancel ($arg...) |
687 | $coro->safe_cancel ($arg...) |
661 | Works mostly like "->cancel", but is inherently "safer", and |
688 | Works mostly like "->cancel", but is inherently "safer", and |
662 | 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 |
663 | in a cancellable state. |
690 | in a cancellable state. Essentially, "->safe_cancel" is a "->cancel" |
|
|
691 | with extra checks before canceling. |
664 | |
692 | |
665 | 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 - |
666 | caught - specifically, it will clean up the thread from within |
694 | specifically, it will clean up the thread from within itself, so all |
667 | itself, so all cleanup handlers (e.g. "guard" blocks) are run with |
695 | cleanup handlers (e.g. "guard" blocks) are run with full thread |
668 | 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 |
669 | 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 |
670 | this method, and therefore, it might fail. It is also considerably |
698 | method, and therefore, it might fail. It is also considerably slower |
671 | slower than "cancel" or "terminate". |
699 | than "cancel" or "terminate". |
672 | |
700 | |
673 | 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 |
674 | 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. |
675 | |
703 | |
676 | 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 |
… | |
… | |
754 | destroyed, that is, after it's resources have been freed but before |
782 | destroyed, that is, after it's resources have been freed but before |
755 | it is joined. The callback gets passed the terminate/cancel |
783 | it is joined. The callback gets passed the terminate/cancel |
756 | arguments, if any, and *must not* die, under any circumstances. |
784 | arguments, if any, and *must not* die, under any circumstances. |
757 | |
785 | |
758 | There can be any number of "on_destroy" callbacks per coro, and |
786 | There can be any number of "on_destroy" callbacks per coro, and |
759 | there is no way currently to remove a callback once added. |
787 | there is currently no way to remove a callback once added. |
760 | |
788 | |
761 | $oldprio = $coro->prio ($newprio) |
789 | $oldprio = $coro->prio ($newprio) |
762 | Sets (or gets, if the argument is missing) the priority of the coro |
790 | Sets (or gets, if the argument is missing) the priority of the coro |
763 | thread. Higher priority coro get run before lower priority coros. |
791 | thread. Higher priority coro get run before lower priority coros. |
764 | Priorities are small signed integers (currently -4 .. +3), that you |
792 | Priorities are small signed integers (currently -4 .. +3), that you |
… | |
… | |
790 | with a coro. |
818 | with a coro. |
791 | |
819 | |
792 | This method simply sets the "$coro->{desc}" member to the given |
820 | This method simply sets the "$coro->{desc}" member to the given |
793 | string. You can modify this member directly if you wish, and in |
821 | string. You can modify this member directly if you wish, and in |
794 | fact, this is often preferred to indicate major processing states |
822 | fact, this is often preferred to indicate major processing states |
795 | that cna then be seen for example in a Coro::Debug session: |
823 | that can then be seen for example in a Coro::Debug session: |
796 | |
824 | |
797 | sub my_long_function { |
825 | sub my_long_function { |
798 | local $Coro::current->{desc} = "now in my_long_function"; |
826 | local $Coro::current->{desc} = "now in my_long_function"; |
799 | ... |
827 | ... |
800 | $Coro::current->{desc} = "my_long_function: phase 1"; |
828 | $Coro::current->{desc} = "my_long_function: phase 1"; |
… | |
… | |
830 | 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 |
831 | 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 |
832 | blocked). |
860 | blocked). |
833 | |
861 | |
834 | 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 |
835 | ("FATAL:$Coro::IDLE blocked itself"), but this is just best effort |
863 | ("FATAL:$Coro::idle blocked itself"), but this is just best effort |
836 | and only works when you do not run your own event loop. |
864 | and only works when you do not run your own event loop. |
837 | |
865 | |
838 | This function allows your callbacks to block by executing them in |
866 | This function allows your callbacks to block by executing them in |
839 | 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 |
840 | 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 |
… | |
… | |
891 | But from within a coro, you often just want to write this: |
919 | But from within a coro, you often just want to write this: |
892 | |
920 | |
893 | my $status = wait_for_child $pid; |
921 | my $status = wait_for_child $pid; |
894 | |
922 | |
895 | Coro offers two functions specifically designed to make this easy, |
923 | Coro offers two functions specifically designed to make this easy, |
896 | "Coro::rouse_cb" and "Coro::rouse_wait". |
924 | "rouse_cb" and "rouse_wait". |
897 | |
925 | |
898 | The first function, "rouse_cb", generates and returns a callback that, |
926 | The first function, "rouse_cb", generates and returns a callback that, |
899 | when invoked, will save its arguments and notify the coro that created |
927 | when invoked, will save its arguments and notify the coro that created |
900 | the callback. |
928 | the callback. |
901 | |
929 | |
… | |
… | |
907 | function mentioned above: |
935 | function mentioned above: |
908 | |
936 | |
909 | sub wait_for_child($) { |
937 | sub wait_for_child($) { |
910 | my ($pid) = @_; |
938 | my ($pid) = @_; |
911 | |
939 | |
912 | my $watcher = AnyEvent->child (pid => $pid, cb => Coro::rouse_cb); |
940 | my $watcher = AnyEvent->child (pid => $pid, cb => rouse_cb); |
913 | |
941 | |
914 | my ($rpid, $rstatus) = Coro::rouse_wait; |
942 | my ($rpid, $rstatus) = rouse_wait; |
915 | $rstatus |
943 | $rstatus |
916 | } |
944 | } |
917 | |
945 | |
918 | In the case where "rouse_cb" and "rouse_wait" are not flexible enough, |
946 | In the case where "rouse_cb" and "rouse_wait" are not flexible enough, |
919 | you can roll your own, using "schedule": |
947 | you can roll your own, using "schedule" and "ready": |
920 | |
948 | |
921 | sub wait_for_child($) { |
949 | sub wait_for_child($) { |
922 | my ($pid) = @_; |
950 | my ($pid) = @_; |
923 | |
951 | |
924 | # store the current coro in $current, |
952 | # store the current coro in $current, |
… | |
… | |
927 | my ($done, $rstatus); |
955 | my ($done, $rstatus); |
928 | |
956 | |
929 | # pass a closure to ->child |
957 | # pass a closure to ->child |
930 | my $watcher = AnyEvent->child (pid => $pid, cb => sub { |
958 | my $watcher = AnyEvent->child (pid => $pid, cb => sub { |
931 | $rstatus = $_[1]; # remember rstatus |
959 | $rstatus = $_[1]; # remember rstatus |
932 | $done = 1; # mark $rstatus as valud |
960 | $done = 1; # mark $rstatus as valid |
|
|
961 | $current->ready; # wake up the waiting thread |
933 | }); |
962 | }); |
934 | |
963 | |
935 | # wait until the closure has been called |
964 | # wait until the closure has been called |
936 | schedule while !$done; |
965 | schedule while !$done; |
937 | |
966 | |