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.267 by root, Wed Aug 26 08:14:09 2009 UTC vs.
Revision 1.274 by root, Sat Dec 12 01:30:26 2009 UTC

… …
67 67
68=cut 68=cut
69 69
70package Coro; 70package Coro;
71 71
72use strict qw(vars subs); 72use common::sense;
73no warnings "uninitialized"; 73
74use Carp ();
74 75
75use Guard (); 76use Guard ();
76 77
77use Coro::State; 78use Coro::State;
78 79
… …
80 81
81our $idle; # idle handler 82our $idle; # idle handler
82our $main; # main coro 83our $main; # main coro
83our $current; # current coro 84our $current; # current coro
84 85
85our $VERSION = 5.17; 86our $VERSION = 5.21;
86 87
87our @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);
88our %EXPORT_TAGS = ( 89our %EXPORT_TAGS = (
89 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)],
90); 91);
91our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready)); 92our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
92 93
… …
123 124
124This 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
125usually 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
126pretty low-level functionality. 127pretty low-level functionality.
127 128
128This 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).
129 131
130If it is a callback, the it is called whenever the scheduler finds no 132The default implementation dies with "FATAL: deadlock detected.", followed
131ready coros to run. The default implementation prints "FATAL: 133by a thread listing, because the program has no other way to continue.
132deadlock detected" and exits, because the program has no other way to
133continue.
134
135If it is a coro object, then this object will be readied (without
136invoking any ready hooks, however) when the scheduler finds no other ready
137coros to run.
138 134
139This hook is overwritten by modules such as C<Coro::EV> and 135This hook is overwritten by modules such as C<Coro::EV> and
140C<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
141coro so the scheduler can run it. 137coro so the scheduler can run it.
142 138
143Note that the callback I<must not>, under any circumstances, block
144the current coro. Normally, this is achieved by having an "idle
145coro" that calls the event loop and then blocks again, and then
146readying that coro in the idle handler, or by simply placing the idle
147coro in this variable.
148
149See 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.
150technique.
151 140
152Please note that if your callback recursively invokes perl (e.g. for event
153handlers), then it must be prepared to be called recursively itself.
154
155=cut 141=cut
156 142
157$idle = sub { 143$idle = new Coro sub {
158 require Carp; 144 require Coro::Debug;
159 Carp::croak ("FATAL: deadlock detected"); 145 die "FATAL: deadlock detected.\n"
146 . Coro::Debug::ps_listing ();
160}; 147};
161 148
162# this coro is necessary because a coro 149# this coro is necessary because a coro
163# cannot destroy itself. 150# cannot destroy itself.
164our @destroy; 151our @destroy;
… …
272=item schedule 259=item schedule
273 260
274Calls the scheduler. The scheduler will find the next coro that is 261Calls 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 262to 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 263to 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 264in its ready queue. If there is no coro ready, it will call the
278C<$Coro::idle> hook. 265C<$Coro::idle> hook.
279 266
280Please note that the current coro will I<not> be put into the ready 267Please 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 268queue, so calling this function usually means you will never be called
282again unless something else (e.g. an event handler) calls C<< ->ready >>, 269again unless something else (e.g. an event handler) calls C<< ->ready >>,
… …
678venerable L<Event|Event> module) are not thread-safe (a weaker form 665venerable L<Event|Event> module) are not thread-safe (a weaker form
679of reentrancy). This means you must not block within event callbacks, 666of reentrancy). This means you must not block within event callbacks,
680otherwise you might suffer from crashes or worse. The only event library 667otherwise 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>. 668currently known that is safe to use without C<unblock_sub> is L<EV>.
682 669
670Coro 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
672only works when you do not run your own event loop.
673
683This function allows your callbacks to block by executing them in another 674This function allows your callbacks to block by executing them in another
684coro where it is safe to block. One example where blocking is handy 675coro 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 676is when you use the L<Coro::AIO|Coro::AIO> functions to save results to
686disk, for example. 677disk, for example.
687 678
… …
728 unshift @unblock_queue, [$cb, @_]; 719 unshift @unblock_queue, [$cb, @_];
729 $unblock_scheduler->ready; 720 $unblock_scheduler->ready;
730 } 721 }
731} 722}
732 723
733=item $cb = Coro::rouse_cb 724=item $cb = rouse_cb
734 725
735Create and return a "rouse callback". That's a code reference that, 726Create and return a "rouse callback". That's a code reference that,
736when called, will remember a copy of its arguments and notify the owner 727when called, will remember a copy of its arguments and notify the owner
737coro of the callback. 728coro of the callback.
738 729
739See the next function. 730See the next function.
740 731
741=item @args = Coro::rouse_wait [$cb] 732=item @args = rouse_wait [$cb]
742 733
743Wait for the specified rouse callback (or the last one that was created in 734Wait for the specified rouse callback (or the last one that was created in
744this coro). 735this coro).
745 736
746As soon as the callback is invoked (or when the callback was invoked 737As soon as the callback is invoked (or when the callback was invoked
… …
843the windows process emulation enabled under unix roughly halves perl 834the windows process emulation enabled under unix roughly halves perl
844performance, even when not used. 835performance, even when not used.
845 836
846=item coro switching is not signal safe 837=item coro switching is not signal safe
847 838
848You must not switch to another coro from within a signal handler 839You must not switch to another coro from within a signal handler (only
849(only relevant with %SIG - most event libraries provide safe signals). 840relevant with %SIG - most event libraries provide safe signals), I<unless>
841you are sure you are not interrupting a Coro function.
850 842
851That means you I<MUST NOT> call any function that might "block" the 843That means you I<MUST NOT> call any function that might "block" the
852current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or 844current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
853anything that calls those. Everything else, including calling C<ready>, 845anything that calls those. Everything else, including calling C<ready>,
854works. 846works.

Diff Legend

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