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.269 by root, Thu Oct 1 23:25:03 2009 UTC vs.
Revision 1.285 by root, Thu Feb 17 01:32:18 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.17; 86our $VERSION = 5.26;
87 87
88our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); 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);
92our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready)); 92our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
93 93
… …
124 124
125This variable is mainly useful to integrate Coro into event loops. It is 125This variable is mainly useful to integrate Coro into event loops. It is
126usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is 126usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is
127pretty low-level functionality. 127pretty low-level functionality.
128 128
129This variable stores either a Coro object or a callback. 129This variable stores a Coro object that is put into the ready queue when
130there are no other ready threads (without invoking any ready hooks).
130 131
131If it is a callback, the it is called whenever the scheduler finds no 132The default implementation dies with "FATAL: deadlock detected.", followed
132ready coros to run. The default implementation prints "FATAL: 133by a thread listing, because the program has no other way to continue.
133deadlock detected" and exits, because the program has no other way to
134continue.
135
136If it is a coro object, then this object will be readied (without
137invoking any ready hooks, however) when the scheduler finds no other ready
138coros to run.
139 134
140This hook is overwritten by modules such as C<Coro::EV> and 135This hook is overwritten by modules such as C<Coro::EV> and
141C<Coro::AnyEvent> to wait on an external event that hopefully wake up a 136C<Coro::AnyEvent> to wait on an external event that hopefully wakes up a
142coro so the scheduler can run it. 137coro so the scheduler can run it.
143 138
144Note that the callback I<must not>, under any circumstances, block
145the current coro. Normally, this is achieved by having an "idle
146coro" that calls the event loop and then blocks again, and then
147readying that coro in the idle handler, or by simply placing the idle
148coro in this variable.
149
150See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this 139See L<Coro::EV> or L<Coro::AnyEvent> for examples of using this technique.
151technique.
152 140
153Please note that if your callback recursively invokes perl (e.g. for event
154handlers), then it must be prepared to be called recursively itself.
155
156=cut 141=cut
157 142
158$idle = sub { 143# ||= because other modules could have provided their own by now
159 Carp::confess ("FATAL: deadlock detected"); 144$idle ||= new Coro sub {
145 require Coro::Debug;
146 die "FATAL: deadlock detected.\n"
147 . Coro::Debug::ps_listing ();
160}; 148};
161 149
162# this coro is necessary because a coro 150# this coro is necessary because a coro
163# cannot destroy itself. 151# cannot destroy itself.
164our @destroy; 152our @destroy;
… …
272=item schedule 260=item schedule
273 261
274Calls the scheduler. The scheduler will find the next coro that is 262Calls the scheduler. The scheduler will find the next coro that is
275to be run from the ready queue and switches to it. The next coro 263to be run from the ready queue and switches to it. The next coro
276to be run is simply the one with the highest priority that is longest 264to be run is simply the one with the highest priority that is longest
277in its ready queue. If there is no coro ready, it will clal the 265in its ready queue. If there is no coro ready, it will call the
278C<$Coro::idle> hook. 266C<$Coro::idle> hook.
279 267
280Please note that the current coro will I<not> be put into the ready 268Please note that the current coro will I<not> be put into the ready
281queue, so calling this function usually means you will never be called 269queue, so calling this function usually means you will never be called
282again unless something else (e.g. an event handler) calls C<< ->ready >>, 270again unless something else (e.g. an event handler) calls C<< ->ready >>,
… …
579 wantarray ? @{$self->{_status}} : $self->{_status}[0]; 567 wantarray ? @{$self->{_status}} : $self->{_status}[0];
580} 568}
581 569
582=item $coro->on_destroy (\&cb) 570=item $coro->on_destroy (\&cb)
583 571
584Registers a callback that is called when this coro gets destroyed, 572Registers a callback that is called when this coro thread gets destroyed,
585but before it is joined. The callback gets passed the terminate arguments, 573but before it is joined. The callback gets passed the terminate arguments,
586if any, and I<must not> die, under any circumstances. 574if any, and I<must not> die, under any circumstances.
587 575
576There can be any number of C<on_destroy> callbacks per coro.
577
588=cut 578=cut
589 579
590sub on_destroy { 580sub on_destroy {
591 my ($self, $cb) = @_; 581 my ($self, $cb) = @_;
592 582
… …
594} 584}
595 585
596=item $oldprio = $coro->prio ($newprio) 586=item $oldprio = $coro->prio ($newprio)
597 587
598Sets (or gets, if the argument is missing) the priority of the 588Sets (or gets, if the argument is missing) the priority of the
599coro. Higher priority coro get run before lower priority 589coro thread. Higher priority coro get run before lower priority
600coro. Priorities are small signed integers (currently -4 .. +3), 590coros. Priorities are small signed integers (currently -4 .. +3),
601that 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
602to get then): 592to get then):
603 593
604 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
605 3 > 1 > 0 > -1 > -3 > -4 595 3 > 1 > 0 > -1 > -3 > -4
606 596
607 # set priority to HIGH 597 # set priority to HIGH
608 current->prio (PRIO_HIGH); 598 current->prio (PRIO_HIGH);
609 599
610The idle coro ($Coro::idle) always has a lower priority than any 600The idle coro thread ($Coro::idle) always has a lower priority than any
611existing coro. 601existing coro.
612 602
613Changing the priority of the current coro will take effect immediately, 603Changing the priority of the current coro will take effect immediately,
614but 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)
615running) will only take effect after the next schedule (of that 605will only take effect after the next schedule (of that coro). This is a
616coro). This is a bug that will be fixed in some future version. 606bug that will be fixed in some future version.
617 607
618=item $newprio = $coro->nice ($change) 608=item $newprio = $coro->nice ($change)
619 609
620Similar 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.
621higher values mean lower priority, just as in unix). 611higher values mean lower priority, just as in UNIX's nice command).
622 612
623=item $olddesc = $coro->desc ($newdesc) 613=item $olddesc = $coro->desc ($newdesc)
624 614
625Sets (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
626coro. 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
627coro. 617coro.
628 618
629This method simply sets the C<< $coro->{desc} >> member to the given 619This method simply sets the C<< $coro->{desc} >> member to the given
630string. 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 }
631 632
632=cut 633=cut
633 634
634sub desc { 635sub desc {
635 my $old = $_[0]{desc}; 636 my $old = $_[0]{desc};
… …
672returning a new coderef. Unblocking means that calling the new coderef 673returning a new coderef. Unblocking means that calling the new coderef
673will return immediately without blocking, returning nothing, while the 674will return immediately without blocking, returning nothing, while the
674original code ref will be called (with parameters) from within another 675original code ref will be called (with parameters) from within another
675coro. 676coro.
676 677
677The reason this function exists is that many event libraries (such as the 678The reason this function exists is that many event libraries (such as
678venerable L<Event|Event> module) are not thread-safe (a weaker form 679the venerable L<Event|Event> module) are not thread-safe (a weaker form
679of reentrancy). This means you must not block within event callbacks, 680of reentrancy). This means you must not block within event callbacks,
680otherwise you might suffer from crashes or worse. The only event library 681otherwise you might suffer from crashes or worse. The only event library
681currently 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).
684
685Coro will try to catch you when you block in the event loop
686("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and
687only works when you do not run your own event loop.
682 688
683This function allows your callbacks to block by executing them in another 689This function allows your callbacks to block by executing them in another
684coro where it is safe to block. One example where blocking is handy 690coro where it is safe to block. One example where blocking is handy
685is when you use the L<Coro::AIO|Coro::AIO> functions to save results to 691is when you use the L<Coro::AIO|Coro::AIO> functions to save results to
686disk, for example. 692disk, for example.
… …
728 unshift @unblock_queue, [$cb, @_]; 734 unshift @unblock_queue, [$cb, @_];
729 $unblock_scheduler->ready; 735 $unblock_scheduler->ready;
730 } 736 }
731} 737}
732 738
733=item $cb = Coro::rouse_cb 739=item $cb = rouse_cb
734 740
735Create and return a "rouse callback". That's a code reference that, 741Create and return a "rouse callback". That's a code reference that,
736when called, will remember a copy of its arguments and notify the owner 742when called, will remember a copy of its arguments and notify the owner
737coro of the callback. 743coro of the callback.
738 744
739See the next function. 745See the next function.
740 746
741=item @args = Coro::rouse_wait [$cb] 747=item @args = rouse_wait [$cb]
742 748
743Wait for the specified rouse callback (or the last one that was created in 749Wait for the specified rouse callback (or the last one that was created in
744this coro). 750this coro).
745 751
746As soon as the callback is invoked (or when the callback was invoked 752As soon as the callback is invoked (or when the callback was invoked
… …
752See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example. 758See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
753 759
754=back 760=back
755 761
756=cut 762=cut
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}
757 777
7581; 7781;
759 779
760=head1 HOW TO WAIT FOR A CALLBACK 780=head1 HOW TO WAIT FOR A CALLBACK
761 781
… …
843the windows process emulation enabled under unix roughly halves perl 863the windows process emulation enabled under unix roughly halves perl
844performance, even when not used. 864performance, even when not used.
845 865
846=item coro switching is not signal safe 866=item coro switching is not signal safe
847 867
848You must not switch to another coro from within a signal handler 868You must not switch to another coro from within a signal handler (only
849(only relevant with %SIG - most event libraries provide safe signals). 869relevant with %SIG - most event libraries provide safe signals), I<unless>
870you are sure you are not interrupting a Coro function.
850 871
851That means you I<MUST NOT> call any function that might "block" the 872That means you I<MUST NOT> call any function that might "block" the
852current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or 873current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
853anything that calls those. Everything else, including calling C<ready>, 874anything that calls those. Everything else, including calling C<ready>,
854works. 875works.
… …
864ithreads (for example, that memory or files would be shared), showing his 885ithreads (for example, that memory or files would be shared), showing his
865lack 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,
866it is probably not obvious to everybody). 887it is probably not obvious to everybody).
867 888
868What 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
869scripting languages given onthe perl workshop 2009: 890scripting languages given on the perl workshop 2009:
870 891
871The so-called "ithreads" were originally implemented for two reasons: 892The so-called "ithreads" were originally implemented for two reasons:
872first, to (badly) emulate unix processes on native win32 perls, and 893first, to (badly) emulate unix processes on native win32 perls, and
873secondly, to replace the older, real thread model ("5.005-threads"). 894secondly, to replace the older, real thread model ("5.005-threads").
874 895

Diff Legend

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