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

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.274 by root, Sat Dec 12 01:30:26 2009 UTC vs.
Revision 1.284 by root, Sun Feb 13 04:39:14 2011 UTC

… …
81 81
82our $idle; # idle handler 82our $idle; # idle handler
83our $main; # main coro 83our $main; # main coro
84our $current; # current coro 84our $current; # current coro
85 85
86our $VERSION = 5.21; 86our $VERSION = 5.26;
87 87
88our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait); 88our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait);
89our %EXPORT_TAGS = ( 89our %EXPORT_TAGS = (
90 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 90 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
91); 91);
… …
138 138
139See L<Coro::EV> or L<Coro::AnyEvent> for examples of using this technique. 139See L<Coro::EV> or L<Coro::AnyEvent> for examples of using this technique.
140 140
141=cut 141=cut
142 142
143# ||= because other modules could have provided their own by now
143$idle = new Coro sub { 144$idle ||= new Coro sub {
144 require Coro::Debug; 145 require Coro::Debug;
145 die "FATAL: deadlock detected.\n" 146 die "FATAL: deadlock detected.\n"
146 . Coro::Debug::ps_listing (); 147 . Coro::Debug::ps_listing ();
147}; 148};
148 149
… …
566 wantarray ? @{$self->{_status}} : $self->{_status}[0]; 567 wantarray ? @{$self->{_status}} : $self->{_status}[0];
567} 568}
568 569
569=item $coro->on_destroy (\&cb) 570=item $coro->on_destroy (\&cb)
570 571
571Registers a callback that is called when this coro gets destroyed, 572Registers a callback that is called when this coro thread gets destroyed,
572but before it is joined. The callback gets passed the terminate arguments, 573but before it is joined. The callback gets passed the terminate arguments,
573if any, and I<must not> die, under any circumstances. 574if any, and I<must not> die, under any circumstances.
574 575
576There can be any number of C<on_destroy> callbacks per coro.
577
575=cut 578=cut
576 579
577sub on_destroy { 580sub on_destroy {
578 my ($self, $cb) = @_; 581 my ($self, $cb) = @_;
579 582
… …
581} 584}
582 585
583=item $oldprio = $coro->prio ($newprio) 586=item $oldprio = $coro->prio ($newprio)
584 587
585Sets (or gets, if the argument is missing) the priority of the 588Sets (or gets, if the argument is missing) the priority of the
586coro. Higher priority coro get run before lower priority 589coro thread. Higher priority coro get run before lower priority
587coro. Priorities are small signed integers (currently -4 .. +3), 590coros. Priorities are small signed integers (currently -4 .. +3),
588that you can refer to using PRIO_xxx constants (use the import tag :prio 591that you can refer to using PRIO_xxx constants (use the import tag :prio
589to get then): 592to get then):
590 593
591 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN 594 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
592 3 > 1 > 0 > -1 > -3 > -4 595 3 > 1 > 0 > -1 > -3 > -4
593 596
594 # set priority to HIGH 597 # set priority to HIGH
595 current->prio (PRIO_HIGH); 598 current->prio (PRIO_HIGH);
596 599
597The idle coro ($Coro::idle) always has a lower priority than any 600The idle coro thread ($Coro::idle) always has a lower priority than any
598existing coro. 601existing coro.
599 602
600Changing the priority of the current coro will take effect immediately, 603Changing the priority of the current coro will take effect immediately,
601but changing the priority of coro in the ready queue (but not 604but changing the priority of a coro in the ready queue (but not running)
602running) will only take effect after the next schedule (of that 605will only take effect after the next schedule (of that coro). This is a
603coro). This is a bug that will be fixed in some future version. 606bug that will be fixed in some future version.
604 607
605=item $newprio = $coro->nice ($change) 608=item $newprio = $coro->nice ($change)
606 609
607Similar to C<prio>, but subtract the given value from the priority (i.e. 610Similar to C<prio>, but subtract the given value from the priority (i.e.
608higher values mean lower priority, just as in unix). 611higher values mean lower priority, just as in UNIX's nice command).
609 612
610=item $olddesc = $coro->desc ($newdesc) 613=item $olddesc = $coro->desc ($newdesc)
611 614
612Sets (or gets in case the argument is missing) the description for this 615Sets (or gets in case the argument is missing) the description for this
613coro. This is just a free-form string you can associate with a 616coro thread. This is just a free-form string you can associate with a
614coro. 617coro.
615 618
616This method simply sets the C<< $coro->{desc} >> member to the given 619This method simply sets the C<< $coro->{desc} >> member to the given
617string. You can modify this member directly if you wish. 620string. You can modify this member directly if you wish, and in fact, this
621is often preferred to indicate major processing states that cna then be
622seen for example in a L<Coro::Debug> session:
623
624 sub my_long_function {
625 local $Coro::current->{desc} = "now in my_long_function";
626 ...
627 $Coro::current->{desc} = "my_long_function: phase 1";
628 ...
629 $Coro::current->{desc} = "my_long_function: phase 2";
630 ...
631 }
618 632
619=cut 633=cut
620 634
621sub desc { 635sub desc {
622 my $old = $_[0]{desc}; 636 my $old = $_[0]{desc};
… …
659returning a new coderef. Unblocking means that calling the new coderef 673returning a new coderef. Unblocking means that calling the new coderef
660will return immediately without blocking, returning nothing, while the 674will return immediately without blocking, returning nothing, while the
661original code ref will be called (with parameters) from within another 675original code ref will be called (with parameters) from within another
662coro. 676coro.
663 677
664The reason this function exists is that many event libraries (such as the 678The reason this function exists is that many event libraries (such as
665venerable L<Event|Event> module) are not thread-safe (a weaker form 679the venerable L<Event|Event> module) are not thread-safe (a weaker form
666of reentrancy). This means you must not block within event callbacks, 680of reentrancy). This means you must not block within event callbacks,
667otherwise you might suffer from crashes or worse. The only event library 681otherwise you might suffer from crashes or worse. The only event library
668currently known that is safe to use without C<unblock_sub> is L<EV>. 682currently known that is safe to use without C<unblock_sub> is L<EV> (but
683you might still run into deadlocks if all event loops are blocked).
669 684
670Coro will try to catch you when you block in the event loop 685Coro will try to catch you when you block in the event loop
671("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and 686("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and
672only works when you do not run your own event loop. 687only works when you do not run your own event loop.
673 688
… …
744 759
745=back 760=back
746 761
747=cut 762=cut
748 763
764for my $module (qw(Channel RWLock Semaphore SemaphoreSet Signal Specific)) {
765 my $old = defined &{"Coro::$module\::new"} && \&{"Coro::$module\::new"};
766
767 *{"Coro::$module\::new"} = sub {
768 require "Coro/$module.pm";
769
770 # some modules have their new predefined in State.xs, some don't
771 *{"Coro::$module\::new"} = $old
772 if $old;
773
774 goto &{"Coro::$module\::new"};
775 };
776}
777
7491; 7781;
750 779
751=head1 HOW TO WAIT FOR A CALLBACK 780=head1 HOW TO WAIT FOR A CALLBACK
752 781
753It is very common for a coro to wait for some callback to be 782It is very common for a coro to wait for some callback to be
… …
856ithreads (for example, that memory or files would be shared), showing his 885ithreads (for example, that memory or files would be shared), showing his
857lack of understanding of this area - if it is hard to understand for Chip, 886lack of understanding of this area - if it is hard to understand for Chip,
858it is probably not obvious to everybody). 887it is probably not obvious to everybody).
859 888
860What follows is an ultra-condensed version of my talk about threads in 889What follows is an ultra-condensed version of my talk about threads in
861scripting languages given onthe perl workshop 2009: 890scripting languages given on the perl workshop 2009:
862 891
863The so-called "ithreads" were originally implemented for two reasons: 892The so-called "ithreads" were originally implemented for two reasons:
864first, to (badly) emulate unix processes on native win32 perls, and 893first, to (badly) emulate unix processes on native win32 perls, and
865secondly, to replace the older, real thread model ("5.005-threads"). 894secondly, to replace the older, real thread model ("5.005-threads").
866 895

Diff Legend

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