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

Comparing Coro/Coro.pm (file contents):
Revision 1.268 by root, Thu Oct 1 23:16:27 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.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 wake 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 warn "oi\n";#d# 144$idle ||= new Coro sub {
160 Carp::confess ("FATAL: deadlock detected"); 145 require Coro::Debug;
146 die "FATAL: deadlock detected.\n"
147 . Coro::Debug::ps_listing ();
161}; 148};
162 149
163# this coro is necessary because a coro 150# this coro is necessary because a coro
164# cannot destroy itself. 151# cannot destroy itself.
165our @destroy; 152our @destroy;
… …
273=item schedule 260=item schedule
274 261
275Calls the scheduler. The scheduler will find the next coro that is 262Calls the scheduler. The scheduler will find the next coro that is
276to 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
277to 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
278in 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
279C<$Coro::idle> hook. 266C<$Coro::idle> hook.
280 267
281Please 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
282queue, so calling this function usually means you will never be called 269queue, so calling this function usually means you will never be called
283again unless something else (e.g. an event handler) calls C<< ->ready >>, 270again unless something else (e.g. an event handler) calls C<< ->ready >>,
… …
580 wantarray ? @{$self->{_status}} : $self->{_status}[0]; 567 wantarray ? @{$self->{_status}} : $self->{_status}[0];
581} 568}
582 569
583=item $coro->on_destroy (\&cb) 570=item $coro->on_destroy (\&cb)
584 571
585Registers a callback that is called when this coro gets destroyed, 572Registers a callback that is called when this coro thread gets destroyed,
586but before it is joined. The callback gets passed the terminate arguments, 573but before it is joined. The callback gets passed the terminate arguments,
587if any, and I<must not> die, under any circumstances. 574if any, and I<must not> die, under any circumstances.
588 575
576There can be any number of C<on_destroy> callbacks per coro.
577
589=cut 578=cut
590 579
591sub on_destroy { 580sub on_destroy {
592 my ($self, $cb) = @_; 581 my ($self, $cb) = @_;
593 582
… …
595} 584}
596 585
597=item $oldprio = $coro->prio ($newprio) 586=item $oldprio = $coro->prio ($newprio)
598 587
599Sets (or gets, if the argument is missing) the priority of the 588Sets (or gets, if the argument is missing) the priority of the
600coro. Higher priority coro get run before lower priority 589coro thread. Higher priority coro get run before lower priority
601coro. Priorities are small signed integers (currently -4 .. +3), 590coros. Priorities are small signed integers (currently -4 .. +3),
602that 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
603to get then): 592to get then):
604 593
605 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
606 3 > 1 > 0 > -1 > -3 > -4 595 3 > 1 > 0 > -1 > -3 > -4
607 596
608 # set priority to HIGH 597 # set priority to HIGH
609 current->prio (PRIO_HIGH); 598 current->prio (PRIO_HIGH);
610 599
611The idle coro ($Coro::idle) always has a lower priority than any 600The idle coro thread ($Coro::idle) always has a lower priority than any
612existing coro. 601existing coro.
613 602
614Changing the priority of the current coro will take effect immediately, 603Changing the priority of the current coro will take effect immediately,
615but 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)
616running) will only take effect after the next schedule (of that 605will only take effect after the next schedule (of that coro). This is a
617coro). This is a bug that will be fixed in some future version. 606bug that will be fixed in some future version.
618 607
619=item $newprio = $coro->nice ($change) 608=item $newprio = $coro->nice ($change)
620 609
621Similar 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.
622higher values mean lower priority, just as in unix). 611higher values mean lower priority, just as in UNIX's nice command).
623 612
624=item $olddesc = $coro->desc ($newdesc) 613=item $olddesc = $coro->desc ($newdesc)
625 614
626Sets (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
627coro. 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
628coro. 617coro.
629 618
630This method simply sets the C<< $coro->{desc} >> member to the given 619This method simply sets the C<< $coro->{desc} >> member to the given
631string. 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 }
632 632
633=cut 633=cut
634 634
635sub desc { 635sub desc {
636 my $old = $_[0]{desc}; 636 my $old = $_[0]{desc};
… …
673returning a new coderef. Unblocking means that calling the new coderef 673returning a new coderef. Unblocking means that calling the new coderef
674will return immediately without blocking, returning nothing, while the 674will return immediately without blocking, returning nothing, while the
675original code ref will be called (with parameters) from within another 675original code ref will be called (with parameters) from within another
676coro. 676coro.
677 677
678The reason this function exists is that many event libraries (such as the 678The reason this function exists is that many event libraries (such as
679venerable L<Event|Event> module) are not thread-safe (a weaker form 679the venerable L<Event|Event> module) are not thread-safe (a weaker form
680of reentrancy). This means you must not block within event callbacks, 680of reentrancy). This means you must not block within event callbacks,
681otherwise you might suffer from crashes or worse. The only event library 681otherwise you might suffer from crashes or worse. The only event library
682currently 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.
683 688
684This function allows your callbacks to block by executing them in another 689This function allows your callbacks to block by executing them in another
685coro 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
686is 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
687disk, for example. 692disk, for example.
… …
729 unshift @unblock_queue, [$cb, @_]; 734 unshift @unblock_queue, [$cb, @_];
730 $unblock_scheduler->ready; 735 $unblock_scheduler->ready;
731 } 736 }
732} 737}
733 738
734=item $cb = Coro::rouse_cb 739=item $cb = rouse_cb
735 740
736Create and return a "rouse callback". That's a code reference that, 741Create and return a "rouse callback". That's a code reference that,
737when 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
738coro of the callback. 743coro of the callback.
739 744
740See the next function. 745See the next function.
741 746
742=item @args = Coro::rouse_wait [$cb] 747=item @args = rouse_wait [$cb]
743 748
744Wait 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
745this coro). 750this coro).
746 751
747As 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
… …
753See 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.
754 759
755=back 760=back
756 761
757=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}
758 777
7591; 7781;
760 779
761=head1 HOW TO WAIT FOR A CALLBACK 780=head1 HOW TO WAIT FOR A CALLBACK
762 781
… …
844the windows process emulation enabled under unix roughly halves perl 863the windows process emulation enabled under unix roughly halves perl
845performance, even when not used. 864performance, even when not used.
846 865
847=item coro switching is not signal safe 866=item coro switching is not signal safe
848 867
849You must not switch to another coro from within a signal handler 868You must not switch to another coro from within a signal handler (only
850(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.
851 871
852That 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
853current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or 873current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
854anything that calls those. Everything else, including calling C<ready>, 874anything that calls those. Everything else, including calling C<ready>,
855works. 875works.
… …
865ithreads (for example, that memory or files would be shared), showing his 885ithreads (for example, that memory or files would be shared), showing his
866lack 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,
867it is probably not obvious to everybody). 887it is probably not obvious to everybody).
868 888
869What 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
870scripting languages given onthe perl workshop 2009: 890scripting languages given on the perl workshop 2009:
871 891
872The so-called "ithreads" were originally implemented for two reasons: 892The so-called "ithreads" were originally implemented for two reasons:
873first, to (badly) emulate unix processes on native win32 perls, and 893first, to (badly) emulate unix processes on native win32 perls, and
874secondly, to replace the older, real thread model ("5.005-threads"). 894secondly, to replace the older, real thread model ("5.005-threads").
875 895

Diff Legend

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