… | |
… | |
195 | |
195 | |
196 | async { |
196 | async { |
197 | Coro::terminate "return value 1", "return value 2"; |
197 | Coro::terminate "return value 1", "return value 2"; |
198 | }; |
198 | }; |
199 | |
199 | |
200 | And yet another way is to C<< ->cancel >> (or C<< ->safe_cancel >>) the |
200 | Yet another way is to C<< ->cancel >> (or C<< ->safe_cancel >>) the coro |
201 | coro thread from another thread: |
201 | thread from another thread: |
202 | |
202 | |
203 | my $coro = async { |
203 | my $coro = async { |
204 | exit 1; |
204 | exit 1; |
205 | }; |
205 | }; |
206 | |
206 | |
… | |
… | |
218 | So, cancelling a thread that runs in an XS event loop might not be the |
218 | So, cancelling a thread that runs in an XS event loop might not be the |
219 | best idea, but any other combination that deals with perl only (cancelling |
219 | best idea, but any other combination that deals with perl only (cancelling |
220 | when a thread is in a C<tie> method or an C<AUTOLOAD> for example) is |
220 | when a thread is in a C<tie> method or an C<AUTOLOAD> for example) is |
221 | safe. |
221 | safe. |
222 | |
222 | |
223 | Lastly, a coro thread object that isn't referenced is C<< ->cancel >>'ed |
223 | Last not least, a coro thread object that isn't referenced is C<< |
224 | automatically - just like other objects in Perl. This is not such a common |
224 | ->cancel >>'ed automatically - just like other objects in Perl. This |
225 | case, however - a running thread is referencedy b C<$Coro::current>, a |
225 | is not such a common case, however - a running thread is referencedy by |
226 | thread ready to run is referenced by the ready queue, a thread waiting |
226 | C<$Coro::current>, a thread ready to run is referenced by the ready queue, |
227 | on a lock or semaphore is referenced by being in some wait list and so |
227 | a thread waiting on a lock or semaphore is referenced by being in some |
228 | on. But a thread that isn't in any of those queues gets cancelled: |
228 | wait list and so on. But a thread that isn't in any of those queues gets |
|
|
229 | cancelled: |
229 | |
230 | |
230 | async { |
231 | async { |
231 | schedule; # cede to other coros, don't go into the ready queue |
232 | schedule; # cede to other coros, don't go into the ready queue |
232 | }; |
233 | }; |
233 | |
234 | |
234 | cede; |
235 | cede; |
235 | # now the async above is destroyed, as it is not referenced by anything. |
236 | # now the async above is destroyed, as it is not referenced by anything. |
|
|
237 | |
|
|
238 | A slightly embellished example might make it clearer: |
|
|
239 | |
|
|
240 | async { |
|
|
241 | my $guard = Guard::guard { print "destroyed\n" }; |
|
|
242 | schedule while 1; |
|
|
243 | }; |
|
|
244 | |
|
|
245 | cede; |
|
|
246 | |
|
|
247 | Superficially one might not expect any output - since the C<async> |
|
|
248 | implements an endless loop, the C<$guard> will not be cleaned up. However, |
|
|
249 | since the thread object returned by C<async> is not stored anywhere, the |
|
|
250 | thread is initially referenced because it is in the ready queue, when it |
|
|
251 | runs it is referenced by C<$Coro::current>, but when it calls C<schedule>, |
|
|
252 | it gets C<cancel>ed causing the guard object to be destroyed (see the next |
|
|
253 | section), and printing it's message. |
|
|
254 | |
|
|
255 | If this seems a bit drastic, remember that this only happens when nothing |
|
|
256 | references the thread anymore, which means there is no way to further |
|
|
257 | execute it, ever. The only options at this point are leaking the thread, |
|
|
258 | or cleaning it up, which brings us to... |
236 | |
259 | |
237 | =item 5. Cleanup |
260 | =item 5. Cleanup |
238 | |
261 | |
239 | Threads will allocate various resources. Most but not all will be returned |
262 | Threads will allocate various resources. Most but not all will be returned |
240 | when a thread terminates, during clean-up. |
263 | when a thread terminates, during clean-up. |
… | |
… | |
259 | |
282 | |
260 | my $sem = new Coro::Semaphore; |
283 | my $sem = new Coro::Semaphore; |
261 | |
284 | |
262 | async { |
285 | async { |
263 | my $lock_guard = $sem->guard; |
286 | my $lock_guard = $sem->guard; |
264 | # if we reutrn, or die or get cancelled, here, |
287 | # if we return, or die or get cancelled, here, |
265 | # then the semaphore will be "up"ed. |
288 | # then the semaphore will be "up"ed. |
266 | }; |
289 | }; |
267 | |
290 | |
268 | The C<Guard::guard> function comes in handy for any custom cleanup you |
291 | The C<Guard::guard> function comes in handy for any custom cleanup you |
269 | might want to do (but you cannot switch to other coroutines form those |
292 | might want to do (but you cannot switch to other coroutines from those |
270 | code blocks): |
293 | code blocks): |
271 | |
294 | |
272 | async { |
295 | async { |
273 | my $window = new Gtk2::Window "toplevel"; |
296 | my $window = new Gtk2::Window "toplevel"; |
274 | # The window will not be cleaned up automatically, even when $window |
297 | # The window will not be cleaned up automatically, even when $window |
… | |
… | |
291 | =item 6. Viva La Zombie Muerte |
314 | =item 6. Viva La Zombie Muerte |
292 | |
315 | |
293 | Even after a thread has terminated and cleaned up its resources, the Coro |
316 | Even after a thread has terminated and cleaned up its resources, the Coro |
294 | object still is there and stores the return values of the thread. |
317 | object still is there and stores the return values of the thread. |
295 | |
318 | |
296 | The means the Coro object gets freed automatically when the thread has |
319 | When there are no other references, it will simply be cleaned up and |
297 | terminated and cleaned up and there arenot other references. |
320 | freed. |
298 | |
321 | |
299 | If there are, the Coro object will stay around, and you can call C<< |
322 | If there areany references, the Coro object will stay around, and you |
300 | ->join >> as many times as you wish to retrieve the result values: |
323 | can call C<< ->join >> as many times as you wish to retrieve the result |
|
|
324 | values: |
301 | |
325 | |
302 | async { |
326 | async { |
303 | print "hi\n"; |
327 | print "hi\n"; |
304 | 1 |
328 | 1 |
305 | }; |
329 | }; |
… | |
… | |
342 | |
366 | |
343 | our $idle; # idle handler |
367 | our $idle; # idle handler |
344 | our $main; # main coro |
368 | our $main; # main coro |
345 | our $current; # current coro |
369 | our $current; # current coro |
346 | |
370 | |
347 | our $VERSION = 5.372; |
371 | our $VERSION = 6.39; |
348 | |
372 | |
349 | our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait); |
373 | our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait); |
350 | our %EXPORT_TAGS = ( |
374 | our %EXPORT_TAGS = ( |
351 | prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], |
375 | prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], |
352 | ); |
376 | ); |
… | |
… | |
357 | =over 4 |
381 | =over 4 |
358 | |
382 | |
359 | =item $Coro::main |
383 | =item $Coro::main |
360 | |
384 | |
361 | This variable stores the Coro object that represents the main |
385 | This variable stores the Coro object that represents the main |
362 | program. While you cna C<ready> it and do most other things you can do to |
386 | program. While you can C<ready> it and do most other things you can do to |
363 | coro, it is mainly useful to compare again C<$Coro::current>, to see |
387 | coro, it is mainly useful to compare again C<$Coro::current>, to see |
364 | whether you are running in the main program or not. |
388 | whether you are running in the main program or not. |
365 | |
389 | |
366 | =cut |
390 | =cut |
367 | |
391 | |
… | |
… | |
628 | Coro::on_enter { |
652 | Coro::on_enter { |
629 | # on entering the thread, we set an VTALRM handler to cede |
653 | # on entering the thread, we set an VTALRM handler to cede |
630 | $SIG{VTALRM} = sub { cede }; |
654 | $SIG{VTALRM} = sub { cede }; |
631 | # and then start the interval timer |
655 | # and then start the interval timer |
632 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01; |
656 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01; |
633 | }; |
657 | }; |
634 | Coro::on_leave { |
658 | Coro::on_leave { |
635 | # on leaving the thread, we stop the interval timer again |
659 | # on leaving the thread, we stop the interval timer again |
636 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0; |
660 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0; |
637 | }; |
661 | }; |
638 | |
662 | |
639 | &{+shift}; |
663 | &{+shift}; |
640 | } |
664 | } |
641 | |
665 | |
642 | # use like this: |
666 | # use like this: |
643 | timeslice { |
667 | timeslice { |
644 | # The following is an endless loop that would normally |
668 | # The following is an endless loop that would normally |
645 | # monopolise the process. Since it runs in a timesliced |
669 | # monopolise the process. Since it runs in a timesliced |
646 | # environment, it will regularly cede to other threads. |
670 | # environment, it will regularly cede to other threads. |
647 | while () { } |
671 | while () { } |
648 | }; |
672 | }; |
649 | |
673 | |
650 | |
674 | |
651 | =item killall |
675 | =item killall |
652 | |
676 | |
653 | Kills/terminates/cancels all coros except the currently running one. |
677 | Kills/terminates/cancels all coros except the currently running one. |
… | |
… | |
766 | current Coro. |
790 | current Coro. |
767 | |
791 | |
768 | This is a rather brutal way to free a coro, with some limitations - if |
792 | This is a rather brutal way to free a coro, with some limitations - if |
769 | the thread is inside a C callback that doesn't expect to be canceled, |
793 | the thread is inside a C callback that doesn't expect to be canceled, |
770 | bad things can happen, or if the cancelled thread insists on running |
794 | bad things can happen, or if the cancelled thread insists on running |
771 | complicated cleanup handlers that rely on it'S thread context, things will |
795 | complicated cleanup handlers that rely on its thread context, things will |
772 | not work. |
796 | not work. |
773 | |
797 | |
774 | Any cleanup code being run (e.g. from C<guard> blocks) will be run without |
798 | Any cleanup code being run (e.g. from C<guard> blocks, destructors and so |
775 | a thread context, and is not allowed to switch to other threads. On the |
799 | on) will be run without a thread context, and is not allowed to switch |
|
|
800 | to other threads. A common mistake is to call C<< ->cancel >> from a |
|
|
801 | destructor called by die'ing inside the thread to be cancelled for |
|
|
802 | example. |
|
|
803 | |
776 | plus side, C<< ->cancel >> will always clean up the thread, no matter |
804 | On the plus side, C<< ->cancel >> will always clean up the thread, no |
777 | what. If your cleanup code is complex or you want to avoid cancelling a |
805 | matter what. If your cleanup code is complex or you want to avoid |
778 | C-thread that doesn't know how to clean up itself, it can be better to C<< |
806 | cancelling a C-thread that doesn't know how to clean up itself, it can be |
779 | ->throw >> an exception, or use C<< ->safe_cancel >>. |
807 | better to C<< ->throw >> an exception, or use C<< ->safe_cancel >>. |
780 | |
808 | |
781 | The arguments to C<< ->cancel >> are not copied, but instead will |
809 | The arguments to C<< ->cancel >> are not copied, but instead will |
782 | be referenced directly (e.g. if you pass C<$var> and after the call |
810 | be referenced directly (e.g. if you pass C<$var> and after the call |
783 | change that variable, then you might change the return values passed to |
811 | change that variable, then you might change the return values passed to |
784 | e.g. C<join>, so don't do that). |
812 | e.g. C<join>, so don't do that). |
… | |
… | |
790 | |
818 | |
791 | =item $coro->safe_cancel ($arg...) |
819 | =item $coro->safe_cancel ($arg...) |
792 | |
820 | |
793 | Works mostly like C<< ->cancel >>, but is inherently "safer", and |
821 | Works mostly like C<< ->cancel >>, but is inherently "safer", and |
794 | consequently, can fail with an exception in cases the thread is not in a |
822 | consequently, can fail with an exception in cases the thread is not in a |
795 | cancellable state. |
823 | cancellable state. Essentially, C<< ->safe_cancel >> is a C<< ->cancel >> |
|
|
824 | with extra checks before canceling. |
796 | |
825 | |
797 | This method works a bit like throwing an exception that cannot be caught |
826 | It works a bit like throwing an exception that cannot be caught - |
798 | - specifically, it will clean up the thread from within itself, so |
827 | specifically, it will clean up the thread from within itself, so all |
799 | all cleanup handlers (e.g. C<guard> blocks) are run with full thread |
828 | cleanup handlers (e.g. C<guard> blocks) are run with full thread |
800 | context and can block if they wish. The downside is that there is no |
829 | context and can block if they wish. The downside is that there is no |
801 | guarantee that the thread can be cancelled when you call this method, and |
830 | guarantee that the thread can be cancelled when you call this method, and |
802 | therefore, it might fail. It is also considerably slower than C<cancel> or |
831 | therefore, it might fail. It is also considerably slower than C<cancel> or |
803 | C<terminate>. |
832 | C<terminate>. |
804 | |
833 | |
… | |
… | |
890 | that is, after it's resources have been freed but before it is joined. The |
919 | that is, after it's resources have been freed but before it is joined. The |
891 | callback gets passed the terminate/cancel arguments, if any, and I<must |
920 | callback gets passed the terminate/cancel arguments, if any, and I<must |
892 | not> die, under any circumstances. |
921 | not> die, under any circumstances. |
893 | |
922 | |
894 | There can be any number of C<on_destroy> callbacks per coro, and there is |
923 | There can be any number of C<on_destroy> callbacks per coro, and there is |
895 | no way currently to remove a callback once added. |
924 | currently no way to remove a callback once added. |
896 | |
925 | |
897 | =item $oldprio = $coro->prio ($newprio) |
926 | =item $oldprio = $coro->prio ($newprio) |
898 | |
927 | |
899 | Sets (or gets, if the argument is missing) the priority of the |
928 | Sets (or gets, if the argument is missing) the priority of the |
900 | coro thread. Higher priority coro get run before lower priority |
929 | coro thread. Higher priority coro get run before lower priority |
… | |
… | |
927 | coro thread. This is just a free-form string you can associate with a |
956 | coro thread. This is just a free-form string you can associate with a |
928 | coro. |
957 | coro. |
929 | |
958 | |
930 | This method simply sets the C<< $coro->{desc} >> member to the given |
959 | This method simply sets the C<< $coro->{desc} >> member to the given |
931 | string. You can modify this member directly if you wish, and in fact, this |
960 | string. You can modify this member directly if you wish, and in fact, this |
932 | is often preferred to indicate major processing states that cna then be |
961 | is often preferred to indicate major processing states that can then be |
933 | seen for example in a L<Coro::Debug> session: |
962 | seen for example in a L<Coro::Debug> session: |
934 | |
963 | |
935 | sub my_long_function { |
964 | sub my_long_function { |
936 | local $Coro::current->{desc} = "now in my_long_function"; |
965 | local $Coro::current->{desc} = "now in my_long_function"; |
937 | ... |
966 | ... |
… | |
… | |
1106 | But from within a coro, you often just want to write this: |
1135 | But from within a coro, you often just want to write this: |
1107 | |
1136 | |
1108 | my $status = wait_for_child $pid; |
1137 | my $status = wait_for_child $pid; |
1109 | |
1138 | |
1110 | Coro offers two functions specifically designed to make this easy, |
1139 | Coro offers two functions specifically designed to make this easy, |
1111 | C<Coro::rouse_cb> and C<Coro::rouse_wait>. |
1140 | C<rouse_cb> and C<rouse_wait>. |
1112 | |
1141 | |
1113 | The first function, C<rouse_cb>, generates and returns a callback that, |
1142 | The first function, C<rouse_cb>, generates and returns a callback that, |
1114 | when invoked, will save its arguments and notify the coro that |
1143 | when invoked, will save its arguments and notify the coro that |
1115 | created the callback. |
1144 | created the callback. |
1116 | |
1145 | |
… | |
… | |
1122 | function mentioned above: |
1151 | function mentioned above: |
1123 | |
1152 | |
1124 | sub wait_for_child($) { |
1153 | sub wait_for_child($) { |
1125 | my ($pid) = @_; |
1154 | my ($pid) = @_; |
1126 | |
1155 | |
1127 | my $watcher = AnyEvent->child (pid => $pid, cb => Coro::rouse_cb); |
1156 | my $watcher = AnyEvent->child (pid => $pid, cb => rouse_cb); |
1128 | |
1157 | |
1129 | my ($rpid, $rstatus) = Coro::rouse_wait; |
1158 | my ($rpid, $rstatus) = rouse_wait; |
1130 | $rstatus |
1159 | $rstatus |
1131 | } |
1160 | } |
1132 | |
1161 | |
1133 | In the case where C<rouse_cb> and C<rouse_wait> are not flexible enough, |
1162 | In the case where C<rouse_cb> and C<rouse_wait> are not flexible enough, |
1134 | you can roll your own, using C<schedule>: |
1163 | you can roll your own, using C<schedule> and C<ready>: |
1135 | |
1164 | |
1136 | sub wait_for_child($) { |
1165 | sub wait_for_child($) { |
1137 | my ($pid) = @_; |
1166 | my ($pid) = @_; |
1138 | |
1167 | |
1139 | # store the current coro in $current, |
1168 | # store the current coro in $current, |
… | |
… | |
1142 | my ($done, $rstatus); |
1171 | my ($done, $rstatus); |
1143 | |
1172 | |
1144 | # pass a closure to ->child |
1173 | # pass a closure to ->child |
1145 | my $watcher = AnyEvent->child (pid => $pid, cb => sub { |
1174 | my $watcher = AnyEvent->child (pid => $pid, cb => sub { |
1146 | $rstatus = $_[1]; # remember rstatus |
1175 | $rstatus = $_[1]; # remember rstatus |
1147 | $done = 1; # mark $rstatus as valud |
1176 | $done = 1; # mark $rstatus as valid |
|
|
1177 | $current->ready; # wake up the waiting thread |
1148 | }); |
1178 | }); |
1149 | |
1179 | |
1150 | # wait until the closure has been called |
1180 | # wait until the closure has been called |
1151 | schedule while !$done; |
1181 | schedule while !$done; |
1152 | |
1182 | |