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.280 by root, Thu Nov 11 15:07:16 2010 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.25;
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 >>,
… …
626Sets (or gets in case the argument is missing) the description for this 613Sets (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 614coro. This is just a free-form string you can associate with a
628coro. 615coro.
629 616
630This method simply sets the C<< $coro->{desc} >> member to the given 617This method simply sets the C<< $coro->{desc} >> member to the given
631string. You can modify this member directly if you wish. 618string. You can modify this member directly if you wish, and in fact, this
619is often preferred to indicate major processing states that cna then be
620seen for example in a L<Coro::Debug> session:
621
622 sub my_long_function {
623 local $Coro::current->{desc} = "now in my_long_function";
624 ...
625 $Coro::current->{desc} = "my_long_function: phase 1";
626 ...
627 $Coro::current->{desc} = "my_long_function: phase 2";
628 ...
629 }
632 630
633=cut 631=cut
634 632
635sub desc { 633sub desc {
636 my $old = $_[0]{desc}; 634 my $old = $_[0]{desc};
… …
678The reason this function exists is that many event libraries (such as the 676The reason this function exists is that many event libraries (such as the
679venerable L<Event|Event> module) are not thread-safe (a weaker form 677venerable L<Event|Event> module) are not thread-safe (a weaker form
680of reentrancy). This means you must not block within event callbacks, 678of reentrancy). This means you must not block within event callbacks,
681otherwise you might suffer from crashes or worse. The only event library 679otherwise 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>. 680currently known that is safe to use without C<unblock_sub> is L<EV>.
681
682Coro will try to catch you when you block in the event loop
683("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and
684only works when you do not run your own event loop.
683 685
684This function allows your callbacks to block by executing them in another 686This function allows your callbacks to block by executing them in another
685coro where it is safe to block. One example where blocking is handy 687coro 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 688is when you use the L<Coro::AIO|Coro::AIO> functions to save results to
687disk, for example. 689disk, for example.
… …
729 unshift @unblock_queue, [$cb, @_]; 731 unshift @unblock_queue, [$cb, @_];
730 $unblock_scheduler->ready; 732 $unblock_scheduler->ready;
731 } 733 }
732} 734}
733 735
734=item $cb = Coro::rouse_cb 736=item $cb = rouse_cb
735 737
736Create and return a "rouse callback". That's a code reference that, 738Create and return a "rouse callback". That's a code reference that,
737when called, will remember a copy of its arguments and notify the owner 739when called, will remember a copy of its arguments and notify the owner
738coro of the callback. 740coro of the callback.
739 741
740See the next function. 742See the next function.
741 743
742=item @args = Coro::rouse_wait [$cb] 744=item @args = rouse_wait [$cb]
743 745
744Wait for the specified rouse callback (or the last one that was created in 746Wait for the specified rouse callback (or the last one that was created in
745this coro). 747this coro).
746 748
747As soon as the callback is invoked (or when the callback was invoked 749As soon as the callback is invoked (or when the callback was invoked
… …
844the windows process emulation enabled under unix roughly halves perl 846the windows process emulation enabled under unix roughly halves perl
845performance, even when not used. 847performance, even when not used.
846 848
847=item coro switching is not signal safe 849=item coro switching is not signal safe
848 850
849You must not switch to another coro from within a signal handler 851You must not switch to another coro from within a signal handler (only
850(only relevant with %SIG - most event libraries provide safe signals). 852relevant with %SIG - most event libraries provide safe signals), I<unless>
853you are sure you are not interrupting a Coro function.
851 854
852That means you I<MUST NOT> call any function that might "block" the 855That means you I<MUST NOT> call any function that might "block" the
853current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or 856current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
854anything that calls those. Everything else, including calling C<ready>, 857anything that calls those. Everything else, including calling C<ready>,
855works. 858works.

Diff Legend

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