… | |
… | |
66 | package Coro; |
66 | package Coro; |
67 | |
67 | |
68 | use strict qw(vars subs); |
68 | use strict qw(vars subs); |
69 | no warnings "uninitialized"; |
69 | no warnings "uninitialized"; |
70 | |
70 | |
|
|
71 | use Guard (); |
|
|
72 | |
71 | use Coro::State; |
73 | use Coro::State; |
72 | |
74 | |
73 | use base qw(Coro::State Exporter); |
75 | use base qw(Coro::State Exporter); |
74 | |
76 | |
75 | our $idle; # idle handler |
77 | our $idle; # idle handler |
76 | our $main; # main coroutine |
78 | our $main; # main coroutine |
77 | our $current; # current coroutine |
79 | our $current; # current coroutine |
78 | |
80 | |
79 | our $VERSION = "5.0"; |
81 | our $VERSION = 5.13; |
80 | |
82 | |
81 | our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); |
83 | our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); |
82 | our %EXPORT_TAGS = ( |
84 | our %EXPORT_TAGS = ( |
83 | prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], |
85 | prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], |
84 | ); |
86 | ); |
… | |
… | |
175 | |
177 | |
176 | =over 4 |
178 | =over 4 |
177 | |
179 | |
178 | =item async { ... } [@args...] |
180 | =item async { ... } [@args...] |
179 | |
181 | |
180 | Create a new coroutine and return it's coroutine object (usually |
182 | Create a new coroutine and return its coroutine object (usually |
181 | unused). The coroutine will be put into the ready queue, so |
183 | unused). The coroutine will be put into the ready queue, so |
182 | it will start running automatically on the next scheduler run. |
184 | it will start running automatically on the next scheduler run. |
183 | |
185 | |
184 | The first argument is a codeblock/closure that should be executed in the |
186 | The first argument is a codeblock/closure that should be executed in the |
185 | coroutine. When it returns argument returns the coroutine is automatically |
187 | coroutine. When it returns argument returns the coroutine is automatically |
… | |
… | |
315 | Terminates the current coroutine with the given status values (see L<cancel>). |
317 | Terminates the current coroutine with the given status values (see L<cancel>). |
316 | |
318 | |
317 | =item killall |
319 | =item killall |
318 | |
320 | |
319 | Kills/terminates/cancels all coroutines except the currently running |
321 | Kills/terminates/cancels all coroutines except the currently running |
320 | one. This is useful after a fork, either in the child or the parent, as |
322 | one. This can be useful after a fork, either in the child or the parent, |
321 | usually only one of them should inherit the running coroutines. |
323 | as usually only one of them should inherit the running coroutines. |
|
|
324 | |
|
|
325 | Note that in the implementation, destructors run as normal, making this |
|
|
326 | function not so useful after a fork. Future versions of this function |
|
|
327 | might try to free resources without running any code. |
322 | |
328 | |
323 | Note that while this will try to free some of the main programs resources, |
329 | Note that while this will try to free some of the main programs resources, |
324 | you cannot free all of them, so if a coroutine that is not the main |
330 | you cannot free all of them, so if a coroutine that is not the main |
325 | program calls this function, there will be some one-time resource leak. |
331 | program calls this function, there will be some one-time resource leak. |
326 | |
332 | |
… | |
… | |
352 | See C<async> and C<Coro::State::new> for additional info about the |
358 | See C<async> and C<Coro::State::new> for additional info about the |
353 | coroutine environment. |
359 | coroutine environment. |
354 | |
360 | |
355 | =cut |
361 | =cut |
356 | |
362 | |
357 | sub _terminate { |
363 | sub _coro_run { |
358 | terminate &{+shift}; |
364 | terminate &{+shift}; |
359 | } |
365 | } |
360 | |
366 | |
361 | =item $success = $coroutine->ready |
367 | =item $success = $coroutine->ready |
362 | |
368 | |
… | |
… | |
537 | would cause a deadlock unless there is an idle handler that wakes up some |
543 | would cause a deadlock unless there is an idle handler that wakes up some |
538 | coroutines. |
544 | coroutines. |
539 | |
545 | |
540 | =item my $guard = Coro::guard { ... } |
546 | =item my $guard = Coro::guard { ... } |
541 | |
547 | |
542 | This creates and returns a guard object. Nothing happens until the object |
548 | This function still exists, but is deprecated. Please use the |
543 | gets destroyed, in which case the codeblock given as argument will be |
549 | C<Guard::guard> function instead. |
544 | executed. This is useful to free locks or other resources in case of a |
|
|
545 | runtime error or when the coroutine gets canceled, as in both cases the |
|
|
546 | guard block will be executed. The guard object supports only one method, |
|
|
547 | C<< ->cancel >>, which will keep the codeblock from being executed. |
|
|
548 | |
550 | |
549 | Example: set some flag and clear it again when the coroutine gets canceled |
|
|
550 | or the function returns: |
|
|
551 | |
|
|
552 | sub do_something { |
|
|
553 | my $guard = Coro::guard { $busy = 0 }; |
|
|
554 | $busy = 1; |
|
|
555 | |
|
|
556 | # do something that requires $busy to be true |
|
|
557 | } |
|
|
558 | |
|
|
559 | =cut |
551 | =cut |
560 | |
552 | |
561 | sub guard(&) { |
553 | BEGIN { *guard = \&Guard::guard } |
562 | bless \(my $cb = $_[0]), "Coro::guard" |
|
|
563 | } |
|
|
564 | |
|
|
565 | sub Coro::guard::cancel { |
|
|
566 | ${$_[0]} = sub { }; |
|
|
567 | } |
|
|
568 | |
|
|
569 | sub Coro::guard::DESTROY { |
|
|
570 | ${$_[0]}->(); |
|
|
571 | } |
|
|
572 | |
|
|
573 | |
554 | |
574 | =item unblock_sub { ... } |
555 | =item unblock_sub { ... } |
575 | |
556 | |
576 | This utility function takes a BLOCK or code reference and "unblocks" it, |
557 | This utility function takes a BLOCK or code reference and "unblocks" it, |
577 | returning a new coderef. Unblocking means that calling the new coderef |
558 | returning a new coderef. Unblocking means that calling the new coderef |
… | |
… | |
681 | |
662 | |
682 | Coro offers two functions specifically designed to make this easy, |
663 | Coro offers two functions specifically designed to make this easy, |
683 | C<Coro::rouse_cb> and C<Coro::rouse_wait>. |
664 | C<Coro::rouse_cb> and C<Coro::rouse_wait>. |
684 | |
665 | |
685 | The first function, C<rouse_cb>, generates and returns a callback that, |
666 | The first function, C<rouse_cb>, generates and returns a callback that, |
686 | when invoked, will save it's arguments and notify the coroutine that |
667 | when invoked, will save its arguments and notify the coroutine that |
687 | created the callback. |
668 | created the callback. |
688 | |
669 | |
689 | The second function, C<rouse_wait>, waits for the callback to be called |
670 | The second function, C<rouse_wait>, waits for the callback to be called |
690 | (by calling C<schedule> to go to sleep) and returns the arguments |
671 | (by calling C<schedule> to go to sleep) and returns the arguments |
691 | originally passed to the callback. |
672 | originally passed to the callback. |