ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Coro/Coro.pm
(Generate patch)

Comparing Coro/Coro.pm (file contents):
Revision 1.321 by root, Sun Feb 2 03:26:06 2014 UTC vs.
Revision 1.342 by root, Sat Jun 25 19:04:04 2016 UTC

… …
366 366
367our $idle; # idle handler 367our $idle; # idle handler
368our $main; # main coro 368our $main; # main coro
369our $current; # current coro 369our $current; # current coro
370 370
371our $VERSION = 6.33; 371our $VERSION = 6.51;
372 372
373our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait); 373our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait);
374our %EXPORT_TAGS = ( 374our %EXPORT_TAGS = (
375 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)],
376); 376);
… …
498C<async> does. As the coro is being reused, stuff like C<on_destroy> 498C<async> does. As the coro is being reused, stuff like C<on_destroy>
499will not work in the expected way, unless you call terminate or cancel, 499will not work in the expected way, unless you call terminate or cancel,
500which somehow defeats the purpose of pooling (but is fine in the 500which somehow defeats the purpose of pooling (but is fine in the
501exceptional case). 501exceptional case).
502 502
503The priority will be reset to C<0> after each run, tracing will be 503The priority will be reset to C<0> after each run, all C<swap_sv> calls
504disabled, the description will be reset and the default output filehandle 504will be undone, tracing will be disabled, the description will be reset
505gets restored, so you can change all these. Otherwise the coro will 505and the default output filehandle gets restored, so you can change all
506be re-used "as-is": most notably if you change other per-coro global 506these. Otherwise the coro will be re-used "as-is": most notably if you
507stuff such as C<$/> you I<must needs> revert that change, which is most 507change other per-coro global stuff such as C<$/> you I<must needs> revert
508simply done by using local as in: C<< local $/ >>. 508that change, which is most simply done by using local as in: C<< local $/
509>>.
509 510
510The idle pool size is limited to C<8> idle coros (this can be 511The idle pool size is limited to C<8> idle coros (this can be
511adjusted by changing $Coro::POOL_SIZE), but there can be as many non-idle 512adjusted by changing $Coro::POOL_SIZE), but there can be as many non-idle
512coros as required. 513coros as required.
513 514
… …
652 Coro::on_enter { 653 Coro::on_enter {
653 # on entering the thread, we set an VTALRM handler to cede 654 # on entering the thread, we set an VTALRM handler to cede
654 $SIG{VTALRM} = sub { cede }; 655 $SIG{VTALRM} = sub { cede };
655 # and then start the interval timer 656 # and then start the interval timer
656 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01; 657 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01;
657 }; 658 };
658 Coro::on_leave { 659 Coro::on_leave {
659 # on leaving the thread, we stop the interval timer again 660 # on leaving the thread, we stop the interval timer again
660 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0; 661 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0;
661 }; 662 };
662 663
663 &{+shift}; 664 &{+shift};
664 } 665 }
665 666
666 # use like this: 667 # use like this:
667 timeslice { 668 timeslice {
668 # The following is an endless loop that would normally 669 # The following is an endless loop that would normally
669 # monopolise the process. Since it runs in a timesliced 670 # monopolise the process. Since it runs in a timesliced
670 # environment, it will regularly cede to other threads. 671 # environment, it will regularly cede to other threads.
671 while () { } 672 while () { }
672 }; 673 };
673 674
674 675
675=item killall 676=item killall
676 677
677Kills/terminates/cancels all coros except the currently running one. 678Kills/terminates/cancels all coros except the currently running one.
… …
793the thread is inside a C callback that doesn't expect to be canceled, 794the thread is inside a C callback that doesn't expect to be canceled,
794bad things can happen, or if the cancelled thread insists on running 795bad things can happen, or if the cancelled thread insists on running
795complicated cleanup handlers that rely on its thread context, things will 796complicated cleanup handlers that rely on its thread context, things will
796not work. 797not work.
797 798
798Any cleanup code being run (e.g. from C<guard> blocks) will be run without 799Any cleanup code being run (e.g. from C<guard> blocks, destructors and so
799a thread context, and is not allowed to switch to other threads. On the 800on) will be run without a thread context, and is not allowed to switch
801to other threads. A common mistake is to call C<< ->cancel >> from a
802destructor called by die'ing inside the thread to be cancelled for
803example.
804
800plus side, C<< ->cancel >> will always clean up the thread, no matter 805On the plus side, C<< ->cancel >> will always clean up the thread, no
801what. If your cleanup code is complex or you want to avoid cancelling a 806matter what. If your cleanup code is complex or you want to avoid
802C-thread that doesn't know how to clean up itself, it can be better to C<< 807cancelling a C-thread that doesn't know how to clean up itself, it can be
803->throw >> an exception, or use C<< ->safe_cancel >>. 808better to C<< ->throw >> an exception, or use C<< ->safe_cancel >>.
804 809
805The arguments to C<< ->cancel >> are not copied, but instead will 810The arguments to C<< ->cancel >> are not copied, but instead will
806be referenced directly (e.g. if you pass C<$var> and after the call 811be referenced directly (e.g. if you pass C<$var> and after the call
807change that variable, then you might change the return values passed to 812change that variable, then you might change the return values passed to
808e.g. C<join>, so don't do that). 813e.g. C<join>, so don't do that).
… …
814 819
815=item $coro->safe_cancel ($arg...) 820=item $coro->safe_cancel ($arg...)
816 821
817Works mostly like C<< ->cancel >>, but is inherently "safer", and 822Works mostly like C<< ->cancel >>, but is inherently "safer", and
818consequently, can fail with an exception in cases the thread is not in a 823consequently, can fail with an exception in cases the thread is not in a
819cancellable state. 824cancellable state. Essentially, C<< ->safe_cancel >> is a C<< ->cancel >>
825with extra checks before canceling.
820 826
821This method works a bit like throwing an exception that cannot be caught 827It works a bit like throwing an exception that cannot be caught -
822- specifically, it will clean up the thread from within itself, so 828specifically, it will clean up the thread from within itself, so all
823all cleanup handlers (e.g. C<guard> blocks) are run with full thread 829cleanup handlers (e.g. C<guard> blocks) are run with full thread
824context and can block if they wish. The downside is that there is no 830context and can block if they wish. The downside is that there is no
825guarantee that the thread can be cancelled when you call this method, and 831guarantee that the thread can be cancelled when you call this method, and
826therefore, it might fail. It is also considerably slower than C<cancel> or 832therefore, it might fail. It is also considerably slower than C<cancel> or
827C<terminate>. 833C<terminate>.
828 834
… …
1016otherwise you might suffer from crashes or worse. The only event library 1022otherwise you might suffer from crashes or worse. The only event library
1017currently known that is safe to use without C<unblock_sub> is L<EV> (but 1023currently known that is safe to use without C<unblock_sub> is L<EV> (but
1018you might still run into deadlocks if all event loops are blocked). 1024you might still run into deadlocks if all event loops are blocked).
1019 1025
1020Coro will try to catch you when you block in the event loop 1026Coro will try to catch you when you block in the event loop
1021("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and 1027("FATAL: $Coro::idle blocked itself"), but this is just best effort and
1022only works when you do not run your own event loop. 1028only works when you do not run your own event loop.
1023 1029
1024This function allows your callbacks to block by executing them in another 1030This function allows your callbacks to block by executing them in another
1025coro where it is safe to block. One example where blocking is handy 1031coro where it is safe to block. One example where blocking is handy
1026is when you use the L<Coro::AIO|Coro::AIO> functions to save results to 1032is when you use the L<Coro::AIO|Coro::AIO> functions to save results to
… …
1296 1302
1297XS API: L<Coro::MakeMaker>. 1303XS API: L<Coro::MakeMaker>.
1298 1304
1299Low level Configuration, Thread Environment, Continuations: L<Coro::State>. 1305Low level Configuration, Thread Environment, Continuations: L<Coro::State>.
1300 1306
1301=head1 AUTHOR 1307=head1 AUTHOR/SUPPORT/CONTACT
1302 1308
1303 Marc Lehmann <schmorp@schmorp.de> 1309 Marc A. Lehmann <schmorp@schmorp.de>
1304 http://home.schmorp.de/ 1310 http://software.schmorp.de/pkg/Coro.html
1305 1311
1306=cut 1312=cut
1307 1313

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines