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

Comparing Coro/Coro.pm (file contents):
Revision 1.85 by root, Sat Nov 25 00:56:35 2006 UTC vs.
Revision 1.91 by root, Fri Dec 1 02:17:37 2006 UTC

… …
41 41
42our $idle; # idle handler 42our $idle; # idle handler
43our $main; # main coroutine 43our $main; # main coroutine
44our $current; # current coroutine 44our $current; # current coroutine
45 45
46our $VERSION = '2.5'; 46our $VERSION = '3.0';
47 47
48our @EXPORT = qw(async cede schedule terminate current); 48our @EXPORT = qw(async cede schedule terminate current);
49our %EXPORT_TAGS = ( 49our %EXPORT_TAGS = (
50 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 50 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
51); 51);
… …
117 117
118=item $idle 118=item $idle
119 119
120A callback that is called whenever the scheduler finds no ready coroutines 120A callback that is called whenever the scheduler finds no ready coroutines
121to run. The default implementation prints "FATAL: deadlock detected" and 121to run. The default implementation prints "FATAL: deadlock detected" and
122exits. 122exits, because the program has no other way to continue.
123 123
124This hook is overwritten by modules such as C<Coro::Timer> and 124This hook is overwritten by modules such as C<Coro::Timer> and
125C<Coro::Event> to wait on an external event that hopefully wakes up some 125C<Coro::Event> to wait on an external event that hopefully wake up a
126coroutine. 126coroutine so the scheduler can run it.
127
128Please note that if your callback recursively invokes perl (e.g. for event
129handlers), then it must be prepared to be called recursively.
127 130
128=cut 131=cut
129 132
130$idle = sub { 133$idle = sub {
131 print STDERR "FATAL: deadlock detected\n"; 134 print STDERR "FATAL: deadlock detected\n";
… …
133}; 136};
134 137
135# this coroutine is necessary because a coroutine 138# this coroutine is necessary because a coroutine
136# cannot destroy itself. 139# cannot destroy itself.
137my @destroy; 140my @destroy;
138my $manager;
139$manager = new Coro sub { 141my $manager; $manager = new Coro sub {
140 while () { 142 while () {
141 # by overwriting the state object with the manager we destroy it 143 # by overwriting the state object with the manager we destroy it
142 # while still being able to schedule this coroutine (in case it has 144 # while still being able to schedule this coroutine (in case it has
143 # been readied multiple times. this is harmless since the manager 145 # been readied multiple times. this is harmless since the manager
144 # can be called as many times as neccessary and will always 146 # can be called as many times as neccessary and will always
… …
172 174
173Create a new asynchronous process and return it's process object 175Create a new asynchronous process and return it's process object
174(usually unused). When the sub returns the new process is automatically 176(usually unused). When the sub returns the new process is automatically
175terminated. 177terminated.
176 178
179Calling C<exit> in a coroutine will not work correctly, so do not do that.
180
177When the coroutine dies, the program will exit, just as in the main 181When the coroutine dies, the program will exit, just as in the main
178program. 182program.
179 183
180 # create a new coroutine that just prints its arguments 184 # create a new coroutine that just prints its arguments
181 async { 185 async {
… …
192 196
193=item schedule 197=item schedule
194 198
195Calls the scheduler. Please note that the current process will not be put 199Calls the scheduler. Please note that the current process will not be put
196into the ready queue, so calling this function usually means you will 200into the ready queue, so calling this function usually means you will
197never be called again. 201never be called again unless something else (e.g. an event handler) calls
202ready.
203
204The canonical way to wait on external events is this:
205
206 {
207 # remember current process
208 my $current = $Coro::current;
209
210 # register a hypothetical event handler
211 on_event_invoke sub {
212 # wake up sleeping coroutine
213 $current->ready;
214 undef $current;
215 };
216
217 # call schedule until event occured.
218 # in case we are woken up for other reasons
219 # (current still defined), loop.
220 Coro::schedule while $current;
221 }
198 222
199=cut 223=cut
200 224
201=item cede 225=item cede
202 226
… …
231Create a new process and return it. When the sub returns the process 255Create a new process and return it. When the sub returns the process
232automatically terminates as if C<terminate> with the returned values were 256automatically terminates as if C<terminate> with the returned values were
233called. To make the process run you must first put it into the ready queue 257called. To make the process run you must first put it into the ready queue
234by calling the ready method. 258by calling the ready method.
235 259
260Calling C<exit> in a coroutine will not work correctly, so do not do that.
261
236=cut 262=cut
237 263
238sub _new_coro { 264sub _new_coro {
239 $current->_clear_idle_sp; # set the idle sp on the following cede
240 _set_cede_self; # ensures that cede cede's us first
241 cede;
242 terminate &{+shift}; 265 terminate &{+shift};
243} 266}
244 267
245sub new { 268sub new {
246 my $class = shift; 269 my $class = shift;
247 270
248 $class->SUPER::new (\&_new_coro, @_) 271 $class->SUPER::new (\&_new_coro, @_)
249} 272}
250 273
251=item $process->ready 274=item $success = $process->ready
252 275
253Put the given process into the ready queue. 276Put the given process into the ready queue (according to it's priority)
277and return true. If the process is already in the ready queue, do nothing
278and return false.
254 279
255=cut 280=item $is_ready = $process->is_ready
281
282Return wether the process is currently the ready queue or not,
256 283
257=item $process->cancel (arg...) 284=item $process->cancel (arg...)
258 285
259Terminates the given process and makes it return the given arguments as 286Terminates the given process and makes it return the given arguments as
260status (default: the empty list). 287status (default: the empty list).

Diff Legend

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