… | |
… | |
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.12; |
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 | ); |
… | |
… | |
312 | |
314 | |
313 | =item terminate [arg...] |
315 | =item terminate [arg...] |
314 | |
316 | |
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 | |
|
|
319 | =item Coro::on_enter BLOCK, Coro::on_leave BLOCK |
|
|
320 | |
|
|
321 | These function install enter and leave winders in the current scope. The |
|
|
322 | enter block will be executed when on_enter is called and whenever the |
|
|
323 | current coroutine is re-entered by the scheduler, while the leave block is |
|
|
324 | executed whenever the current coroutine is blocked by the scheduler, and |
|
|
325 | also when the containing scope is exited (by whatever means, be it exit, |
|
|
326 | die, last etc.). |
|
|
327 | |
|
|
328 | I<Neither invoking the scheduler, nor exceptions, are allowed within those |
|
|
329 | BLOCKs>. That means: do not even think about calling C<die> without an |
|
|
330 | eval, and do not even think of entering the scheduler in any way. |
|
|
331 | |
|
|
332 | Since both BLOCKs are tied to the current scope, they will automatically |
|
|
333 | be removed when the current scope exits. |
|
|
334 | |
|
|
335 | These functions implement the same concept as C<dynamic-wind> in scheme |
|
|
336 | does, and are useful when you want to localise some resource to a specific |
|
|
337 | coroutine. |
|
|
338 | |
|
|
339 | They slow down coroutine switching considerably for coroutines that use |
|
|
340 | them (But coroutine switching is still reasonably fast if the handlers are |
|
|
341 | fast). |
|
|
342 | |
|
|
343 | These functions are best understood by an example: The following function |
|
|
344 | will change the current timezone to "Antarctica/South_Pole", which |
|
|
345 | requires a call to C<tzset>, but by using C<on_enter> and C<on_leave>, |
|
|
346 | which remember/change the current timezone and restore the previous |
|
|
347 | value, respectively, the timezone is only changes for the coroutine that |
|
|
348 | installed those handlers. |
|
|
349 | |
|
|
350 | use POSIX qw(tzset); |
|
|
351 | |
|
|
352 | async { |
|
|
353 | my $old_tz; # store outside TZ value here |
|
|
354 | |
|
|
355 | Coro::on_enter { |
|
|
356 | $old_tz = $ENV{TZ}; # remember the old value |
|
|
357 | |
|
|
358 | $ENV{TZ} = "Antarctica/South_Pole"; |
|
|
359 | tzset; # enable new value |
|
|
360 | }; |
|
|
361 | |
|
|
362 | Coro::on_leave { |
|
|
363 | $ENV{TZ} = $old_tz; |
|
|
364 | tzset; # restore old value |
|
|
365 | }; |
|
|
366 | |
|
|
367 | # at this place, the timezone is Antarctica/South_Pole, |
|
|
368 | # without disturbing the TZ of any other coroutine. |
|
|
369 | }; |
|
|
370 | |
|
|
371 | This can be used to localise about any resource (locale, uid, current |
|
|
372 | working directory etc.) to a block, despite the existance of other |
|
|
373 | coroutines. |
|
|
374 | |
317 | =item killall |
375 | =item killall |
318 | |
376 | |
319 | Kills/terminates/cancels all coroutines except the currently running |
377 | Kills/terminates/cancels all coroutines except the currently running one. |
320 | one. This is useful after a fork, either in the child or the parent, as |
|
|
321 | usually only one of them should inherit the running coroutines. |
|
|
322 | |
378 | |
323 | Note that while this will try to free some of the main programs resources, |
379 | Note that while this will try to free some of the main interpreter |
|
|
380 | resources if the calling coroutine isn't the main coroutine, but one |
324 | you cannot free all of them, so if a coroutine that is not the main |
381 | cannot free all of them, so if a coroutine that is not the main coroutine |
325 | program calls this function, there will be some one-time resource leak. |
382 | calls this function, there will be some one-time resource leak. |
326 | |
383 | |
327 | =cut |
384 | =cut |
328 | |
385 | |
329 | sub killall { |
386 | sub killall { |
330 | for (Coro::State::list) { |
387 | for (Coro::State::list) { |
… | |
… | |
537 | would cause a deadlock unless there is an idle handler that wakes up some |
594 | would cause a deadlock unless there is an idle handler that wakes up some |
538 | coroutines. |
595 | coroutines. |
539 | |
596 | |
540 | =item my $guard = Coro::guard { ... } |
597 | =item my $guard = Coro::guard { ... } |
541 | |
598 | |
542 | This creates and returns a guard object. Nothing happens until the object |
599 | This function still exists, but is deprecated. Please use the |
543 | gets destroyed, in which case the codeblock given as argument will be |
600 | 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 | |
601 | |
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 |
602 | =cut |
560 | |
603 | |
561 | sub guard(&) { |
604 | 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 | |
605 | |
574 | =item unblock_sub { ... } |
606 | =item unblock_sub { ... } |
575 | |
607 | |
576 | This utility function takes a BLOCK or code reference and "unblocks" it, |
608 | This utility function takes a BLOCK or code reference and "unblocks" it, |
577 | returning a new coderef. Unblocking means that calling the new coderef |
609 | returning a new coderef. Unblocking means that calling the new coderef |