… | |
… | |
16 | cede; # yield to coro |
16 | cede; # yield to coro |
17 | print "3\n"; |
17 | print "3\n"; |
18 | cede; # and again |
18 | cede; # and again |
19 | |
19 | |
20 | # use locking |
20 | # use locking |
21 | use Coro::Semaphore; |
|
|
22 | my $lock = new Coro::Semaphore; |
21 | my $lock = new Coro::Semaphore; |
23 | my $locked; |
22 | my $locked; |
24 | |
23 | |
25 | $lock->down; |
24 | $lock->down; |
26 | $locked = 1; |
25 | $locked = 1; |
… | |
… | |
196 | |
195 | |
197 | async { |
196 | async { |
198 | Coro::terminate "return value 1", "return value 2"; |
197 | Coro::terminate "return value 1", "return value 2"; |
199 | }; |
198 | }; |
200 | |
199 | |
201 | 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 |
202 | coro thread from another thread: |
201 | thread from another thread: |
203 | |
202 | |
204 | my $coro = async { |
203 | my $coro = async { |
205 | exit 1; |
204 | exit 1; |
206 | }; |
205 | }; |
207 | |
206 | |
… | |
… | |
219 | 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 |
220 | 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 |
221 | 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 |
222 | safe. |
221 | safe. |
223 | |
222 | |
224 | 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<< |
225 | automatically - just like other objects in Perl. This is not such a common |
224 | ->cancel >>'ed automatically - just like other objects in Perl. This |
226 | 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 |
227 | 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, |
228 | 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 |
229 | 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: |
230 | |
230 | |
231 | async { |
231 | async { |
232 | 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 |
233 | }; |
233 | }; |
234 | |
234 | |
235 | cede; |
235 | cede; |
236 | # 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... |
237 | |
259 | |
238 | =item 5. Cleanup |
260 | =item 5. Cleanup |
239 | |
261 | |
240 | 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 |
241 | when a thread terminates, during clean-up. |
263 | when a thread terminates, during clean-up. |
… | |
… | |
260 | |
282 | |
261 | my $sem = new Coro::Semaphore; |
283 | my $sem = new Coro::Semaphore; |
262 | |
284 | |
263 | async { |
285 | async { |
264 | my $lock_guard = $sem->guard; |
286 | my $lock_guard = $sem->guard; |
265 | # if we reutrn, or die or get cancelled, here, |
287 | # if we return, or die or get cancelled, here, |
266 | # then the semaphore will be "up"ed. |
288 | # then the semaphore will be "up"ed. |
267 | }; |
289 | }; |
268 | |
290 | |
269 | 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 |
270 | 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 |
271 | code blocks): |
293 | code blocks): |
272 | |
294 | |
273 | async { |
295 | async { |
274 | my $window = new Gtk2::Window "toplevel"; |
296 | my $window = new Gtk2::Window "toplevel"; |
275 | # The window will not be cleaned up automatically, even when $window |
297 | # The window will not be cleaned up automatically, even when $window |
… | |
… | |
292 | =item 6. Viva La Zombie Muerte |
314 | =item 6. Viva La Zombie Muerte |
293 | |
315 | |
294 | 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 |
295 | 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. |
296 | |
318 | |
297 | 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 |
298 | terminated and cleaned up and there arenot other references. |
320 | freed. |
299 | |
321 | |
300 | 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 |
301 | ->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: |
302 | |
325 | |
303 | async { |
326 | async { |
304 | print "hi\n"; |
327 | print "hi\n"; |
305 | 1 |
328 | 1 |
306 | }; |
329 | }; |
… | |
… | |
343 | |
366 | |
344 | our $idle; # idle handler |
367 | our $idle; # idle handler |
345 | our $main; # main coro |
368 | our $main; # main coro |
346 | our $current; # current coro |
369 | our $current; # current coro |
347 | |
370 | |
348 | our $VERSION = 5.372; |
371 | our $VERSION = 6.49; |
349 | |
372 | |
350 | 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); |
351 | our %EXPORT_TAGS = ( |
374 | our %EXPORT_TAGS = ( |
352 | 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)], |
353 | ); |
376 | ); |
… | |
… | |
358 | =over 4 |
381 | =over 4 |
359 | |
382 | |
360 | =item $Coro::main |
383 | =item $Coro::main |
361 | |
384 | |
362 | This variable stores the Coro object that represents the main |
385 | This variable stores the Coro object that represents the main |
363 | 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 |
364 | 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 |
365 | whether you are running in the main program or not. |
388 | whether you are running in the main program or not. |
366 | |
389 | |
367 | =cut |
390 | =cut |
368 | |
391 | |
… | |
… | |
629 | Coro::on_enter { |
652 | Coro::on_enter { |
630 | # on entering the thread, we set an VTALRM handler to cede |
653 | # on entering the thread, we set an VTALRM handler to cede |
631 | $SIG{VTALRM} = sub { cede }; |
654 | $SIG{VTALRM} = sub { cede }; |
632 | # and then start the interval timer |
655 | # and then start the interval timer |
633 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01; |
656 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01; |
634 | }; |
657 | }; |
635 | Coro::on_leave { |
658 | Coro::on_leave { |
636 | # on leaving the thread, we stop the interval timer again |
659 | # on leaving the thread, we stop the interval timer again |
637 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0; |
660 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0; |
638 | }; |
661 | }; |
639 | |
662 | |
640 | &{+shift}; |
663 | &{+shift}; |
641 | } |
664 | } |
642 | |
665 | |
643 | # use like this: |
666 | # use like this: |
644 | timeslice { |
667 | timeslice { |
645 | # The following is an endless loop that would normally |
668 | # The following is an endless loop that would normally |
646 | # monopolise the process. Since it runs in a timesliced |
669 | # monopolise the process. Since it runs in a timesliced |
647 | # environment, it will regularly cede to other threads. |
670 | # environment, it will regularly cede to other threads. |
648 | while () { } |
671 | while () { } |
649 | }; |
672 | }; |
650 | |
673 | |
651 | |
674 | |
652 | =item killall |
675 | =item killall |
653 | |
676 | |
654 | Kills/terminates/cancels all coros except the currently running one. |
677 | Kills/terminates/cancels all coros except the currently running one. |
… | |
… | |
767 | current Coro. |
790 | current Coro. |
768 | |
791 | |
769 | 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 |
770 | 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, |
771 | 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 |
772 | complicated cleanup handlers that rely on it'S thread context, things will |
795 | complicated cleanup handlers that rely on its thread context, things will |
773 | not work. |
796 | not work. |
774 | |
797 | |
775 | 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 |
776 | 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 | |
777 | 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 |
778 | 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 |
779 | 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 |
780 | ->throw >> an exception, or use C<< ->safe_cancel >>. |
807 | better to C<< ->throw >> an exception, or use C<< ->safe_cancel >>. |
781 | |
808 | |
782 | The arguments to C<< ->cancel >> are not copied, but instead will |
809 | The arguments to C<< ->cancel >> are not copied, but instead will |
783 | 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 |
784 | 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 |
785 | e.g. C<join>, so don't do that). |
812 | e.g. C<join>, so don't do that). |
… | |
… | |
791 | |
818 | |
792 | =item $coro->safe_cancel ($arg...) |
819 | =item $coro->safe_cancel ($arg...) |
793 | |
820 | |
794 | Works mostly like C<< ->cancel >>, but is inherently "safer", and |
821 | Works mostly like C<< ->cancel >>, but is inherently "safer", and |
795 | 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 |
796 | cancellable state. |
823 | cancellable state. Essentially, C<< ->safe_cancel >> is a C<< ->cancel >> |
|
|
824 | with extra checks before canceling. |
797 | |
825 | |
798 | 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 - |
799 | - specifically, it will clean up the thread from within itself, so |
827 | specifically, it will clean up the thread from within itself, so all |
800 | 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 |
801 | 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 |
802 | 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 |
803 | 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 |
804 | C<terminate>. |
832 | C<terminate>. |
805 | |
833 | |
… | |
… | |
891 | 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 |
892 | 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 |
893 | not> die, under any circumstances. |
921 | not> die, under any circumstances. |
894 | |
922 | |
895 | 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 |
896 | no way currently to remove a callback once added. |
924 | currently no way to remove a callback once added. |
897 | |
925 | |
898 | =item $oldprio = $coro->prio ($newprio) |
926 | =item $oldprio = $coro->prio ($newprio) |
899 | |
927 | |
900 | 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 |
901 | coro thread. Higher priority coro get run before lower priority |
929 | coro thread. Higher priority coro get run before lower priority |
… | |
… | |
928 | 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 |
929 | coro. |
957 | coro. |
930 | |
958 | |
931 | 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 |
932 | 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 |
933 | 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 |
934 | seen for example in a L<Coro::Debug> session: |
962 | seen for example in a L<Coro::Debug> session: |
935 | |
963 | |
936 | sub my_long_function { |
964 | sub my_long_function { |
937 | local $Coro::current->{desc} = "now in my_long_function"; |
965 | local $Coro::current->{desc} = "now in my_long_function"; |
938 | ... |
966 | ... |
… | |
… | |
993 | otherwise you might suffer from crashes or worse. The only event library |
1021 | otherwise you might suffer from crashes or worse. The only event library |
994 | currently known that is safe to use without C<unblock_sub> is L<EV> (but |
1022 | currently known that is safe to use without C<unblock_sub> is L<EV> (but |
995 | you might still run into deadlocks if all event loops are blocked). |
1023 | you might still run into deadlocks if all event loops are blocked). |
996 | |
1024 | |
997 | Coro will try to catch you when you block in the event loop |
1025 | Coro will try to catch you when you block in the event loop |
998 | ("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and |
1026 | ("FATAL: $Coro::idle blocked itself"), but this is just best effort and |
999 | only works when you do not run your own event loop. |
1027 | only works when you do not run your own event loop. |
1000 | |
1028 | |
1001 | This function allows your callbacks to block by executing them in another |
1029 | This function allows your callbacks to block by executing them in another |
1002 | coro where it is safe to block. One example where blocking is handy |
1030 | coro where it is safe to block. One example where blocking is handy |
1003 | is when you use the L<Coro::AIO|Coro::AIO> functions to save results to |
1031 | is when you use the L<Coro::AIO|Coro::AIO> functions to save results to |
… | |
… | |
1107 | 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: |
1108 | |
1136 | |
1109 | my $status = wait_for_child $pid; |
1137 | my $status = wait_for_child $pid; |
1110 | |
1138 | |
1111 | Coro offers two functions specifically designed to make this easy, |
1139 | Coro offers two functions specifically designed to make this easy, |
1112 | C<Coro::rouse_cb> and C<Coro::rouse_wait>. |
1140 | C<rouse_cb> and C<rouse_wait>. |
1113 | |
1141 | |
1114 | 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, |
1115 | when invoked, will save its arguments and notify the coro that |
1143 | when invoked, will save its arguments and notify the coro that |
1116 | created the callback. |
1144 | created the callback. |
1117 | |
1145 | |
… | |
… | |
1123 | function mentioned above: |
1151 | function mentioned above: |
1124 | |
1152 | |
1125 | sub wait_for_child($) { |
1153 | sub wait_for_child($) { |
1126 | my ($pid) = @_; |
1154 | my ($pid) = @_; |
1127 | |
1155 | |
1128 | my $watcher = AnyEvent->child (pid => $pid, cb => Coro::rouse_cb); |
1156 | my $watcher = AnyEvent->child (pid => $pid, cb => rouse_cb); |
1129 | |
1157 | |
1130 | my ($rpid, $rstatus) = Coro::rouse_wait; |
1158 | my ($rpid, $rstatus) = rouse_wait; |
1131 | $rstatus |
1159 | $rstatus |
1132 | } |
1160 | } |
1133 | |
1161 | |
1134 | 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, |
1135 | you can roll your own, using C<schedule>: |
1163 | you can roll your own, using C<schedule> and C<ready>: |
1136 | |
1164 | |
1137 | sub wait_for_child($) { |
1165 | sub wait_for_child($) { |
1138 | my ($pid) = @_; |
1166 | my ($pid) = @_; |
1139 | |
1167 | |
1140 | # store the current coro in $current, |
1168 | # store the current coro in $current, |
… | |
… | |
1143 | my ($done, $rstatus); |
1171 | my ($done, $rstatus); |
1144 | |
1172 | |
1145 | # pass a closure to ->child |
1173 | # pass a closure to ->child |
1146 | my $watcher = AnyEvent->child (pid => $pid, cb => sub { |
1174 | my $watcher = AnyEvent->child (pid => $pid, cb => sub { |
1147 | $rstatus = $_[1]; # remember rstatus |
1175 | $rstatus = $_[1]; # remember rstatus |
1148 | $done = 1; # mark $rstatus as valud |
1176 | $done = 1; # mark $rstatus as valid |
|
|
1177 | $current->ready; # wake up the waiting thread |
1149 | }); |
1178 | }); |
1150 | |
1179 | |
1151 | # wait until the closure has been called |
1180 | # wait until the closure has been called |
1152 | schedule while !$done; |
1181 | schedule while !$done; |
1153 | |
1182 | |
… | |
… | |
1272 | |
1301 | |
1273 | XS API: L<Coro::MakeMaker>. |
1302 | XS API: L<Coro::MakeMaker>. |
1274 | |
1303 | |
1275 | Low level Configuration, Thread Environment, Continuations: L<Coro::State>. |
1304 | Low level Configuration, Thread Environment, Continuations: L<Coro::State>. |
1276 | |
1305 | |
1277 | =head1 AUTHOR |
1306 | =head1 AUTHOR/SUPPORT/CONTACT |
1278 | |
1307 | |
1279 | Marc Lehmann <schmorp@schmorp.de> |
1308 | Marc A. Lehmann <schmorp@schmorp.de> |
1280 | http://home.schmorp.de/ |
1309 | http://software.schmorp.de/pkg/Coro.html |
1281 | |
1310 | |
1282 | =cut |
1311 | =cut |
1283 | |
1312 | |