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

Comparing Coro/Coro.pm (file contents):
Revision 1.233 by root, Fri Nov 21 06:02:07 2008 UTC vs.
Revision 1.248 by root, Mon Dec 15 15:03:31 2008 UTC

1=head1 NAME 1=head1 NAME
2 2
3Coro - coroutine process abstraction 3Coro - the only real threads in perl
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use Coro; 7 use Coro;
8 8
… …
11 print "2\n"; 11 print "2\n";
12 cede; # yield back to main 12 cede; # yield back to main
13 print "4\n"; 13 print "4\n";
14 }; 14 };
15 print "1\n"; 15 print "1\n";
16 cede; # yield to coroutine 16 cede; # yield to coro
17 print "3\n"; 17 print "3\n";
18 cede; # and again 18 cede; # and again
19 19
20 # use locking 20 # use locking
21 use Coro::Semaphore; 21 use Coro::Semaphore;
… …
26 $locked = 1; 26 $locked = 1;
27 $lock->up; 27 $lock->up;
28 28
29=head1 DESCRIPTION 29=head1 DESCRIPTION
30 30
31This module collection manages coroutines. Coroutines are similar to 31For a tutorial-style introduction, please read the L<Coro::Intro>
32threads but don't (in general) run in parallel at the same time even 32manpage. This manpage mainly contains reference information.
33on SMP machines. The specific flavor of coroutine used in this module
34also guarantees you that it will not switch between coroutines unless
35necessary, at easily-identified points in your program, so locking and
36parallel access are rarely an issue, making coroutine programming much
37safer and easier than threads programming.
38 33
39Unlike a normal perl program, however, coroutines allow you to have 34This module collection manages continuations in general, most often in
40multiple running interpreters that share data, which is especially useful 35the form of cooperative threads (also called coros, or simply "coro"
41to code pseudo-parallel processes and for event-based programming, such as 36in the documentation). They are similar to kernel threads but don't (in
42multiple HTTP-GET requests running concurrently. See L<Coro::AnyEvent> to 37general) run in parallel at the same time even on SMP machines. The
43learn more. 38specific flavor of thread offered by this module also guarantees you that
39it will not switch between threads unless necessary, at easily-identified
40points in your program, so locking and parallel access are rarely an
41issue, making thread programming much safer and easier than using other
42thread models.
44 43
45Coroutines are also useful because Perl has no support for threads (the so 44Unlike the so-called "Perl threads" (which are not actually real threads
46called "threads" that perl offers are nothing more than the (bad) process 45but only the windows process emulation ported to unix), Coro provides a
47emulation coming from the Windows platform: On standard operating systems 46full shared address space, which makes communication between threads
48they serve no purpose whatsoever, except by making your programs slow and 47very easy. And threads are fast, too: disabling the Windows process
49making them use a lot of memory. Best disable them when building perl, or 48emulation code in your perl and using Coro can easily result in a two to
50aks your software vendor/distributor to do it for you). 49four times speed increase for your programs.
51 50
51Coro achieves that by supporting multiple running interpreters that share
52data, which is especially useful to code pseudo-parallel processes and
53for event-based programming, such as multiple HTTP-GET requests running
54concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro
55into an event-based environment.
56
52In this module, coroutines are defined as "callchain + lexical variables + 57In this module, a thread is defined as "callchain + lexical variables +
53@_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own callchain, 58@_ + $_ + $@ + $/ + C stack), that is, a thread has its own callchain,
54its own set of lexicals and its own set of perls most important global 59its own set of lexicals and its own set of perls most important global
55variables (see L<Coro::State> for more configuration). 60variables (see L<Coro::State> for more configuration and background info).
61
62See also the C<SEE ALSO> section at the end of this document - the Coro
63module family is quite large.
56 64
57=cut 65=cut
58 66
59package Coro; 67package Coro;
60 68
61use strict qw(vars subs); 69use strict qw(vars subs);
62no warnings "uninitialized"; 70no warnings "uninitialized";
63 71
72use Guard ();
73
64use Coro::State; 74use Coro::State;
65 75
66use base qw(Coro::State Exporter); 76use base qw(Coro::State Exporter);
67 77
68our $idle; # idle handler 78our $idle; # idle handler
69our $main; # main coroutine 79our $main; # main coro
70our $current; # current coroutine 80our $current; # current coro
71 81
72our $VERSION = "5.0"; 82our $VERSION = 5.13;
73 83
74our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); 84our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
75our %EXPORT_TAGS = ( 85our %EXPORT_TAGS = (
76 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 86 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
77); 87);
78our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready)); 88our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
79 89
90=head1 GLOBAL VARIABLES
91
80=over 4 92=over 4
81 93
82=item $Coro::main 94=item $Coro::main
83 95
84This variable stores the coroutine object that represents the main 96This variable stores the Coro object that represents the main
85program. While you cna C<ready> it and do most other things you can do to 97program. While you cna C<ready> it and do most other things you can do to
86coroutines, it is mainly useful to compare again C<$Coro::current>, to see 98coro, it is mainly useful to compare again C<$Coro::current>, to see
87whether you are running in the main program or not. 99whether you are running in the main program or not.
88 100
89=cut 101=cut
90 102
91# $main is now being initialised by Coro::State 103# $main is now being initialised by Coro::State
92 104
93=item $Coro::current 105=item $Coro::current
94 106
95The coroutine object representing the current coroutine (the last 107The Coro object representing the current coro (the last
96coroutine that the Coro scheduler switched to). The initial value is 108coro that the Coro scheduler switched to). The initial value is
97C<$Coro::main> (of course). 109C<$Coro::main> (of course).
98 110
99This variable is B<strictly> I<read-only>. You can take copies of the 111This variable is B<strictly> I<read-only>. You can take copies of the
100value stored in it and use it as any other coroutine object, but you must 112value stored in it and use it as any other Coro object, but you must
101not otherwise modify the variable itself. 113not otherwise modify the variable itself.
102 114
103=cut 115=cut
104 116
105sub current() { $current } # [DEPRECATED] 117sub current() { $current } # [DEPRECATED]
106 118
107=item $Coro::idle 119=item $Coro::idle
108 120
109This variable is mainly useful to integrate Coro into event loops. It is 121This variable is mainly useful to integrate Coro into event loops. It is
110usually better to rely on L<Coro::AnyEvent> or LC<Coro::EV>, as this is 122usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is
111pretty low-level functionality. 123pretty low-level functionality.
112 124
113This variable stores a callback that is called whenever the scheduler 125This variable stores either a Coro object or a callback.
126
127If it is a callback, the it is called whenever the scheduler finds no
114finds no ready coroutines to run. The default implementation prints 128ready coros to run. The default implementation prints "FATAL:
115"FATAL: deadlock detected" and exits, because the program has no other way 129deadlock detected" and exits, because the program has no other way to
116to continue. 130continue.
117 131
132If it is a coro object, then this object will be readied (without
133invoking any ready hooks, however) when the scheduler finds no other ready
134coros to run.
135
118This hook is overwritten by modules such as C<Coro::Timer> and 136This hook is overwritten by modules such as C<Coro::EV> and
119C<Coro::AnyEvent> to wait on an external event that hopefully wake up a 137C<Coro::AnyEvent> to wait on an external event that hopefully wake up a
120coroutine so the scheduler can run it. 138coro so the scheduler can run it.
121 139
122Note that the callback I<must not>, under any circumstances, block 140Note that the callback I<must not>, under any circumstances, block
123the current coroutine. Normally, this is achieved by having an "idle 141the current coro. Normally, this is achieved by having an "idle
124coroutine" that calls the event loop and then blocks again, and then 142coro" that calls the event loop and then blocks again, and then
125readying that coroutine in the idle handler. 143readying that coro in the idle handler, or by simply placing the idle
144coro in this variable.
126 145
127See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this 146See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this
128technique. 147technique.
129 148
130Please note that if your callback recursively invokes perl (e.g. for event 149Please note that if your callback recursively invokes perl (e.g. for event
… …
135$idle = sub { 154$idle = sub {
136 require Carp; 155 require Carp;
137 Carp::croak ("FATAL: deadlock detected"); 156 Carp::croak ("FATAL: deadlock detected");
138}; 157};
139 158
140# this coroutine is necessary because a coroutine 159# this coro is necessary because a coro
141# cannot destroy itself. 160# cannot destroy itself.
142our @destroy; 161our @destroy;
143our $manager; 162our $manager;
144 163
145$manager = new Coro sub { 164$manager = new Coro sub {
146 while () { 165 while () {
147 Coro::_cancel shift @destroy 166 Coro::State::cancel shift @destroy
148 while @destroy; 167 while @destroy;
149 168
150 &schedule; 169 &schedule;
151 } 170 }
152}; 171};
153$manager->{desc} = "[coro manager]"; 172$manager->{desc} = "[coro manager]";
154$manager->prio (PRIO_MAX); 173$manager->prio (PRIO_MAX);
155 174
156=back 175=back
157 176
158=head2 SIMPLE COROUTINE CREATION 177=head1 SIMPLE CORO CREATION
159 178
160=over 4 179=over 4
161 180
162=item async { ... } [@args...] 181=item async { ... } [@args...]
163 182
164Create a new coroutine and return it's coroutine object (usually 183Create a new coro and return its Coro object (usually
165unused). The coroutine will be put into the ready queue, so 184unused). The coro will be put into the ready queue, so
166it will start running automatically on the next scheduler run. 185it will start running automatically on the next scheduler run.
167 186
168The first argument is a codeblock/closure that should be executed in the 187The first argument is a codeblock/closure that should be executed in the
169coroutine. When it returns argument returns the coroutine is automatically 188coro. When it returns argument returns the coro is automatically
170terminated. 189terminated.
171 190
172The remaining arguments are passed as arguments to the closure. 191The remaining arguments are passed as arguments to the closure.
173 192
174See the C<Coro::State::new> constructor for info about the coroutine 193See the C<Coro::State::new> constructor for info about the coro
175environment in which coroutines are executed. 194environment in which coro are executed.
176 195
177Calling C<exit> in a coroutine will do the same as calling exit outside 196Calling C<exit> in a coro will do the same as calling exit outside
178the coroutine. Likewise, when the coroutine dies, the program will exit, 197the coro. Likewise, when the coro dies, the program will exit,
179just as it would in the main program. 198just as it would in the main program.
180 199
181If you do not want that, you can provide a default C<die> handler, or 200If you do not want that, you can provide a default C<die> handler, or
182simply avoid dieing (by use of C<eval>). 201simply avoid dieing (by use of C<eval>).
183 202
184Example: Create a new coroutine that just prints its arguments. 203Example: Create a new coro that just prints its arguments.
185 204
186 async { 205 async {
187 print "@_\n"; 206 print "@_\n";
188 } 1,2,3,4; 207 } 1,2,3,4;
189 208
… …
195 $coro 214 $coro
196} 215}
197 216
198=item async_pool { ... } [@args...] 217=item async_pool { ... } [@args...]
199 218
200Similar to C<async>, but uses a coroutine pool, so you should not call 219Similar to C<async>, but uses a coro pool, so you should not call
201terminate or join on it (although you are allowed to), and you get a 220terminate or join on it (although you are allowed to), and you get a
202coroutine that might have executed other code already (which can be good 221coro that might have executed other code already (which can be good
203or bad :). 222or bad :).
204 223
205On the plus side, this function is about twice as fast as creating (and 224On the plus side, this function is about twice as fast as creating (and
206destroying) a completely new coroutine, so if you need a lot of generic 225destroying) a completely new coro, so if you need a lot of generic
207coroutines in quick successsion, use C<async_pool>, not C<async>. 226coros in quick successsion, use C<async_pool>, not C<async>.
208 227
209The code block is executed in an C<eval> context and a warning will be 228The code block is executed in an C<eval> context and a warning will be
210issued in case of an exception instead of terminating the program, as 229issued in case of an exception instead of terminating the program, as
211C<async> does. As the coroutine is being reused, stuff like C<on_destroy> 230C<async> does. As the coro is being reused, stuff like C<on_destroy>
212will not work in the expected way, unless you call terminate or cancel, 231will not work in the expected way, unless you call terminate or cancel,
213which somehow defeats the purpose of pooling (but is fine in the 232which somehow defeats the purpose of pooling (but is fine in the
214exceptional case). 233exceptional case).
215 234
216The priority will be reset to C<0> after each run, tracing will be 235The priority will be reset to C<0> after each run, tracing will be
217disabled, the description will be reset and the default output filehandle 236disabled, the description will be reset and the default output filehandle
218gets restored, so you can change all these. Otherwise the coroutine will 237gets restored, so you can change all these. Otherwise the coro will
219be re-used "as-is": most notably if you change other per-coroutine global 238be re-used "as-is": most notably if you change other per-coro global
220stuff such as C<$/> you I<must needs> revert that change, which is most 239stuff such as C<$/> you I<must needs> revert that change, which is most
221simply done by using local as in: C<< local $/ >>. 240simply done by using local as in: C<< local $/ >>.
222 241
223The idle pool size is limited to C<8> idle coroutines (this can be 242The idle pool size is limited to C<8> idle coros (this can be
224adjusted by changing $Coro::POOL_SIZE), but there can be as many non-idle 243adjusted by changing $Coro::POOL_SIZE), but there can be as many non-idle
225coros as required. 244coros as required.
226 245
227If you are concerned about pooled coroutines growing a lot because a 246If you are concerned about pooled coros growing a lot because a
228single C<async_pool> used a lot of stackspace you can e.g. C<async_pool 247single C<async_pool> used a lot of stackspace you can e.g. C<async_pool
229{ terminate }> once per second or so to slowly replenish the pool. In 248{ terminate }> once per second or so to slowly replenish the pool. In
230addition to that, when the stacks used by a handler grows larger than 32kb 249addition to that, when the stacks used by a handler grows larger than 32kb
231(adjustable via $Coro::POOL_RSS) it will also be destroyed. 250(adjustable via $Coro::POOL_RSS) it will also be destroyed.
232 251
… …
246 } 265 }
247} 266}
248 267
249=back 268=back
250 269
251=head2 STATIC METHODS 270=head1 STATIC METHODS
252 271
253Static methods are actually functions that operate on the current coroutine. 272Static methods are actually functions that implicitly operate on the
273current coro.
254 274
255=over 4 275=over 4
256 276
257=item schedule 277=item schedule
258 278
259Calls the scheduler. The scheduler will find the next coroutine that is 279Calls the scheduler. The scheduler will find the next coro that is
260to be run from the ready queue and switches to it. The next coroutine 280to be run from the ready queue and switches to it. The next coro
261to be run is simply the one with the highest priority that is longest 281to be run is simply the one with the highest priority that is longest
262in its ready queue. If there is no coroutine ready, it will clal the 282in its ready queue. If there is no coro ready, it will clal the
263C<$Coro::idle> hook. 283C<$Coro::idle> hook.
264 284
265Please note that the current coroutine will I<not> be put into the ready 285Please note that the current coro will I<not> be put into the ready
266queue, so calling this function usually means you will never be called 286queue, so calling this function usually means you will never be called
267again unless something else (e.g. an event handler) calls C<< ->ready >>, 287again unless something else (e.g. an event handler) calls C<< ->ready >>,
268thus waking you up. 288thus waking you up.
269 289
270This makes C<schedule> I<the> generic method to use to block the current 290This makes C<schedule> I<the> generic method to use to block the current
271coroutine and wait for events: first you remember the current coroutine in 291coro and wait for events: first you remember the current coro in
272a variable, then arrange for some callback of yours to call C<< ->ready 292a variable, then arrange for some callback of yours to call C<< ->ready
273>> on that once some event happens, and last you call C<schedule> to put 293>> on that once some event happens, and last you call C<schedule> to put
274yourself to sleep. Note that a lot of things can wake your coroutine up, 294yourself to sleep. Note that a lot of things can wake your coro up,
275so you need to check whether the event indeed happened, e.g. by storing the 295so you need to check whether the event indeed happened, e.g. by storing the
276status in a variable. 296status in a variable.
277 297
278See B<HOW TO WAIT FOR A CALLBACK>, below, for some ways to wait for callbacks. 298See B<HOW TO WAIT FOR A CALLBACK>, below, for some ways to wait for callbacks.
279 299
280=item cede 300=item cede
281 301
282"Cede" to other coroutines. This function puts the current coroutine into 302"Cede" to other coros. This function puts the current coro into
283the ready queue and calls C<schedule>, which has the effect of giving 303the ready queue and calls C<schedule>, which has the effect of giving
284up the current "timeslice" to other coroutines of the same or higher 304up the current "timeslice" to other coros of the same or higher
285priority. Once your coroutine gets its turn again it will automatically be 305priority. Once your coro gets its turn again it will automatically be
286resumed. 306resumed.
287 307
288This function is often called C<yield> in other languages. 308This function is often called C<yield> in other languages.
289 309
290=item Coro::cede_notself 310=item Coro::cede_notself
291 311
292Works like cede, but is not exported by default and will cede to I<any> 312Works like cede, but is not exported by default and will cede to I<any>
293coroutine, regardless of priority. This is useful sometimes to ensure 313coro, regardless of priority. This is useful sometimes to ensure
294progress is made. 314progress is made.
295 315
296=item terminate [arg...] 316=item terminate [arg...]
297 317
298Terminates the current coroutine with the given status values (see L<cancel>). 318Terminates the current coro with the given status values (see L<cancel>).
319
320=item Coro::on_enter BLOCK, Coro::on_leave BLOCK
321
322These function install enter and leave winders in the current scope. The
323enter block will be executed when on_enter is called and whenever the
324current coro is re-entered by the scheduler, while the leave block is
325executed whenever the current coro is blocked by the scheduler, and
326also when the containing scope is exited (by whatever means, be it exit,
327die, last etc.).
328
329I<Neither invoking the scheduler, nor exceptions, are allowed within those
330BLOCKs>. That means: do not even think about calling C<die> without an
331eval, and do not even think of entering the scheduler in any way.
332
333Since both BLOCKs are tied to the current scope, they will automatically
334be removed when the current scope exits.
335
336These functions implement the same concept as C<dynamic-wind> in scheme
337does, and are useful when you want to localise some resource to a specific
338coro.
339
340They slow down coro switching considerably for coros that use
341them (But coro switching is still reasonably fast if the handlers are
342fast).
343
344These functions are best understood by an example: The following function
345will change the current timezone to "Antarctica/South_Pole", which
346requires a call to C<tzset>, but by using C<on_enter> and C<on_leave>,
347which remember/change the current timezone and restore the previous
348value, respectively, the timezone is only changes for the coro that
349installed those handlers.
350
351 use POSIX qw(tzset);
352
353 async {
354 my $old_tz; # store outside TZ value here
355
356 Coro::on_enter {
357 $old_tz = $ENV{TZ}; # remember the old value
358
359 $ENV{TZ} = "Antarctica/South_Pole";
360 tzset; # enable new value
361 };
362
363 Coro::on_leave {
364 $ENV{TZ} = $old_tz;
365 tzset; # restore old value
366 };
367
368 # at this place, the timezone is Antarctica/South_Pole,
369 # without disturbing the TZ of any other coro.
370 };
371
372This can be used to localise about any resource (locale, uid, current
373working directory etc.) to a block, despite the existance of other
374coros.
299 375
300=item killall 376=item killall
301 377
302Kills/terminates/cancels all coroutines except the currently running 378Kills/terminates/cancels all coros except the currently running one.
303one. This is useful after a fork, either in the child or the parent, as
304usually only one of them should inherit the running coroutines.
305 379
306Note that while this will try to free some of the main programs resources, 380Note that while this will try to free some of the main interpreter
381resources if the calling coro isn't the main coro, but one
307you cannot free all of them, so if a coroutine that is not the main 382cannot free all of them, so if a coro that is not the main coro
308program calls this function, there will be some one-time resource leak. 383calls this function, there will be some one-time resource leak.
309 384
310=cut 385=cut
311 386
312sub killall { 387sub killall {
313 for (Coro::State::list) { 388 for (Coro::State::list) {
… …
316 } 391 }
317} 392}
318 393
319=back 394=back
320 395
321=head2 COROUTINE METHODS 396=head1 CORO OBJECT METHODS
322 397
323These are the methods you can call on coroutine objects (or to create 398These are the methods you can call on coro objects (or to create
324them). 399them).
325 400
326=over 4 401=over 4
327 402
328=item new Coro \&sub [, @args...] 403=item new Coro \&sub [, @args...]
329 404
330Create a new coroutine and return it. When the sub returns, the coroutine 405Create a new coro and return it. When the sub returns, the coro
331automatically terminates as if C<terminate> with the returned values were 406automatically terminates as if C<terminate> with the returned values were
332called. To make the coroutine run you must first put it into the ready 407called. To make the coro run you must first put it into the ready
333queue by calling the ready method. 408queue by calling the ready method.
334 409
335See C<async> and C<Coro::State::new> for additional info about the 410See C<async> and C<Coro::State::new> for additional info about the
336coroutine environment. 411coro environment.
337 412
338=cut 413=cut
339 414
340sub _terminate { 415sub _coro_run {
341 terminate &{+shift}; 416 terminate &{+shift};
342} 417}
343 418
344=item $success = $coroutine->ready 419=item $success = $coro->ready
345 420
346Put the given coroutine into the end of its ready queue (there is one 421Put the given coro into the end of its ready queue (there is one
347queue for each priority) and return true. If the coroutine is already in 422queue for each priority) and return true. If the coro is already in
348the ready queue, do nothing and return false. 423the ready queue, do nothing and return false.
349 424
350This ensures that the scheduler will resume this coroutine automatically 425This ensures that the scheduler will resume this coro automatically
351once all the coroutines of higher priority and all coroutines of the same 426once all the coro of higher priority and all coro of the same
352priority that were put into the ready queue earlier have been resumed. 427priority that were put into the ready queue earlier have been resumed.
353 428
354=item $is_ready = $coroutine->is_ready 429=item $is_ready = $coro->is_ready
355 430
356Return whether the coroutine is currently the ready queue or not, 431Returns true iff the Coro object is in the ready queue. Unless the Coro
432object gets destroyed, it will eventually be scheduled by the scheduler.
357 433
434=item $is_running = $coro->is_running
435
436Returns true iff the Coro object is currently running. Only one Coro object
437can ever be in the running state (but it currently is possible to have
438multiple running Coro::States).
439
440=item $is_suspended = $coro->is_suspended
441
442Returns true iff this Coro object has been suspended. Suspended Coros will
443not ever be scheduled.
444
358=item $coroutine->cancel (arg...) 445=item $coro->cancel (arg...)
359 446
360Terminates the given coroutine and makes it return the given arguments as 447Terminates the given Coro and makes it return the given arguments as
361status (default: the empty list). Never returns if the coroutine is the 448status (default: the empty list). Never returns if the Coro is the
362current coroutine. 449current Coro.
363 450
364=cut 451=cut
365 452
366sub cancel { 453sub cancel {
367 my $self = shift; 454 my $self = shift;
368 455
369 if ($current == $self) { 456 if ($current == $self) {
370 terminate @_; 457 terminate @_;
371 } else { 458 } else {
372 $self->{_status} = [@_]; 459 $self->{_status} = [@_];
373 $self->_cancel; 460 Coro::State::cancel $self;
374 } 461 }
375} 462}
376 463
377=item $coroutine->schedule_to 464=item $coro->schedule_to
378 465
379Puts the current coroutine to sleep (like C<Coro::schedule>), but instead 466Puts the current coro to sleep (like C<Coro::schedule>), but instead
380of continuing with the next coro from the ready queue, always switch to 467of continuing with the next coro from the ready queue, always switch to
381the given coroutine object (regardless of priority etc.). The readyness 468the given coro object (regardless of priority etc.). The readyness
382state of that coroutine isn't changed. 469state of that coro isn't changed.
383 470
384This is an advanced method for special cases - I'd love to hear about any 471This is an advanced method for special cases - I'd love to hear about any
385uses for this one. 472uses for this one.
386 473
387=item $coroutine->cede_to 474=item $coro->cede_to
388 475
389Like C<schedule_to>, but puts the current coroutine into the ready 476Like C<schedule_to>, but puts the current coro into the ready
390queue. This has the effect of temporarily switching to the given 477queue. This has the effect of temporarily switching to the given
391coroutine, and continuing some time later. 478coro, and continuing some time later.
392 479
393This is an advanced method for special cases - I'd love to hear about any 480This is an advanced method for special cases - I'd love to hear about any
394uses for this one. 481uses for this one.
395 482
396=item $coroutine->throw ([$scalar]) 483=item $coro->throw ([$scalar])
397 484
398If C<$throw> is specified and defined, it will be thrown as an exception 485If C<$throw> is specified and defined, it will be thrown as an exception
399inside the coroutine at the next convenient point in time. Otherwise 486inside the coro at the next convenient point in time. Otherwise
400clears the exception object. 487clears the exception object.
401 488
402Coro will check for the exception each time a schedule-like-function 489Coro will check for the exception each time a schedule-like-function
403returns, i.e. after each C<schedule>, C<cede>, C<< Coro::Semaphore->down 490returns, i.e. after each C<schedule>, C<cede>, C<< Coro::Semaphore->down
404>>, C<< Coro::Handle->readable >> and so on. Most of these functions 491>>, C<< Coro::Handle->readable >> and so on. Most of these functions
… …
406 493
407The exception object will be thrown "as is" with the specified scalar in 494The exception object will be thrown "as is" with the specified scalar in
408C<$@>, i.e. if it is a string, no line number or newline will be appended 495C<$@>, i.e. if it is a string, no line number or newline will be appended
409(unlike with C<die>). 496(unlike with C<die>).
410 497
411This can be used as a softer means than C<cancel> to ask a coroutine to 498This can be used as a softer means than C<cancel> to ask a coro to
412end itself, although there is no guarantee that the exception will lead to 499end itself, although there is no guarantee that the exception will lead to
413termination, and if the exception isn't caught it might well end the whole 500termination, and if the exception isn't caught it might well end the whole
414program. 501program.
415 502
416You might also think of C<throw> as being the moral equivalent of 503You might also think of C<throw> as being the moral equivalent of
417C<kill>ing a coroutine with a signal (in this case, a scalar). 504C<kill>ing a coro with a signal (in this case, a scalar).
418 505
419=item $coroutine->join 506=item $coro->join
420 507
421Wait until the coroutine terminates and return any values given to the 508Wait until the coro terminates and return any values given to the
422C<terminate> or C<cancel> functions. C<join> can be called concurrently 509C<terminate> or C<cancel> functions. C<join> can be called concurrently
423from multiple coroutines, and all will be resumed and given the status 510from multiple coro, and all will be resumed and given the status
424return once the C<$coroutine> terminates. 511return once the C<$coro> terminates.
425 512
426=cut 513=cut
427 514
428sub join { 515sub join {
429 my $self = shift; 516 my $self = shift;
… …
440 } 527 }
441 528
442 wantarray ? @{$self->{_status}} : $self->{_status}[0]; 529 wantarray ? @{$self->{_status}} : $self->{_status}[0];
443} 530}
444 531
445=item $coroutine->on_destroy (\&cb) 532=item $coro->on_destroy (\&cb)
446 533
447Registers a callback that is called when this coroutine gets destroyed, 534Registers a callback that is called when this coro gets destroyed,
448but before it is joined. The callback gets passed the terminate arguments, 535but before it is joined. The callback gets passed the terminate arguments,
449if any, and I<must not> die, under any circumstances. 536if any, and I<must not> die, under any circumstances.
450 537
451=cut 538=cut
452 539
… …
454 my ($self, $cb) = @_; 541 my ($self, $cb) = @_;
455 542
456 push @{ $self->{_on_destroy} }, $cb; 543 push @{ $self->{_on_destroy} }, $cb;
457} 544}
458 545
459=item $oldprio = $coroutine->prio ($newprio) 546=item $oldprio = $coro->prio ($newprio)
460 547
461Sets (or gets, if the argument is missing) the priority of the 548Sets (or gets, if the argument is missing) the priority of the
462coroutine. Higher priority coroutines get run before lower priority 549coro. Higher priority coro get run before lower priority
463coroutines. Priorities are small signed integers (currently -4 .. +3), 550coro. Priorities are small signed integers (currently -4 .. +3),
464that you can refer to using PRIO_xxx constants (use the import tag :prio 551that you can refer to using PRIO_xxx constants (use the import tag :prio
465to get then): 552to get then):
466 553
467 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN 554 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
468 3 > 1 > 0 > -1 > -3 > -4 555 3 > 1 > 0 > -1 > -3 > -4
469 556
470 # set priority to HIGH 557 # set priority to HIGH
471 current->prio(PRIO_HIGH); 558 current->prio (PRIO_HIGH);
472 559
473The idle coroutine ($Coro::idle) always has a lower priority than any 560The idle coro ($Coro::idle) always has a lower priority than any
474existing coroutine. 561existing coro.
475 562
476Changing the priority of the current coroutine will take effect immediately, 563Changing the priority of the current coro will take effect immediately,
477but changing the priority of coroutines in the ready queue (but not 564but changing the priority of coro in the ready queue (but not
478running) will only take effect after the next schedule (of that 565running) will only take effect after the next schedule (of that
479coroutine). This is a bug that will be fixed in some future version. 566coro). This is a bug that will be fixed in some future version.
480 567
481=item $newprio = $coroutine->nice ($change) 568=item $newprio = $coro->nice ($change)
482 569
483Similar to C<prio>, but subtract the given value from the priority (i.e. 570Similar to C<prio>, but subtract the given value from the priority (i.e.
484higher values mean lower priority, just as in unix). 571higher values mean lower priority, just as in unix).
485 572
486=item $olddesc = $coroutine->desc ($newdesc) 573=item $olddesc = $coro->desc ($newdesc)
487 574
488Sets (or gets in case the argument is missing) the description for this 575Sets (or gets in case the argument is missing) the description for this
489coroutine. This is just a free-form string you can associate with a 576coro. This is just a free-form string you can associate with a
490coroutine. 577coro.
491 578
492This method simply sets the C<< $coroutine->{desc} >> member to the given 579This method simply sets the C<< $coro->{desc} >> member to the given
493string. You can modify this member directly if you wish. 580string. You can modify this member directly if you wish.
494 581
495=cut 582=cut
496 583
497sub desc { 584sub desc {
… …
505 Carp::croak ("You must not call ->transfer on Coro objects. Use Coro::State objects or the ->schedule_to method. Caught"); 592 Carp::croak ("You must not call ->transfer on Coro objects. Use Coro::State objects or the ->schedule_to method. Caught");
506} 593}
507 594
508=back 595=back
509 596
510=head2 GLOBAL FUNCTIONS 597=head1 GLOBAL FUNCTIONS
511 598
512=over 4 599=over 4
513 600
514=item Coro::nready 601=item Coro::nready
515 602
516Returns the number of coroutines that are currently in the ready state, 603Returns the number of coro that are currently in the ready state,
517i.e. that can be switched to by calling C<schedule> directory or 604i.e. that can be switched to by calling C<schedule> directory or
518indirectly. The value C<0> means that the only runnable coroutine is the 605indirectly. The value C<0> means that the only runnable coro is the
519currently running one, so C<cede> would have no effect, and C<schedule> 606currently running one, so C<cede> would have no effect, and C<schedule>
520would cause a deadlock unless there is an idle handler that wakes up some 607would cause a deadlock unless there is an idle handler that wakes up some
521coroutines. 608coro.
522 609
523=item my $guard = Coro::guard { ... } 610=item my $guard = Coro::guard { ... }
524 611
525This creates and returns a guard object. Nothing happens until the object 612This function still exists, but is deprecated. Please use the
526gets destroyed, in which case the codeblock given as argument will be 613C<Guard::guard> function instead.
527executed. This is useful to free locks or other resources in case of a
528runtime error or when the coroutine gets canceled, as in both cases the
529guard block will be executed. The guard object supports only one method,
530C<< ->cancel >>, which will keep the codeblock from being executed.
531 614
532Example: set some flag and clear it again when the coroutine gets canceled
533or the function returns:
534
535 sub do_something {
536 my $guard = Coro::guard { $busy = 0 };
537 $busy = 1;
538
539 # do something that requires $busy to be true
540 }
541
542=cut 615=cut
543 616
544sub guard(&) { 617BEGIN { *guard = \&Guard::guard }
545 bless \(my $cb = $_[0]), "Coro::guard"
546}
547
548sub Coro::guard::cancel {
549 ${$_[0]} = sub { };
550}
551
552sub Coro::guard::DESTROY {
553 ${$_[0]}->();
554}
555
556 618
557=item unblock_sub { ... } 619=item unblock_sub { ... }
558 620
559This utility function takes a BLOCK or code reference and "unblocks" it, 621This utility function takes a BLOCK or code reference and "unblocks" it,
560returning a new coderef. Unblocking means that calling the new coderef 622returning a new coderef. Unblocking means that calling the new coderef
561will return immediately without blocking, returning nothing, while the 623will return immediately without blocking, returning nothing, while the
562original code ref will be called (with parameters) from within another 624original code ref will be called (with parameters) from within another
563coroutine. 625coro.
564 626
565The reason this function exists is that many event libraries (such as the 627The reason this function exists is that many event libraries (such as the
566venerable L<Event|Event> module) are not coroutine-safe (a weaker form 628venerable L<Event|Event> module) are not thread-safe (a weaker form
567of thread-safety). This means you must not block within event callbacks, 629of reentrancy). This means you must not block within event callbacks,
568otherwise you might suffer from crashes or worse. The only event library 630otherwise you might suffer from crashes or worse. The only event library
569currently known that is safe to use without C<unblock_sub> is L<EV>. 631currently known that is safe to use without C<unblock_sub> is L<EV>.
570 632
571This function allows your callbacks to block by executing them in another 633This function allows your callbacks to block by executing them in another
572coroutine where it is safe to block. One example where blocking is handy 634coro where it is safe to block. One example where blocking is handy
573is when you use the L<Coro::AIO|Coro::AIO> functions to save results to 635is when you use the L<Coro::AIO|Coro::AIO> functions to save results to
574disk, for example. 636disk, for example.
575 637
576In short: simply use C<unblock_sub { ... }> instead of C<sub { ... }> when 638In short: simply use C<unblock_sub { ... }> instead of C<sub { ... }> when
577creating event callbacks that want to block. 639creating event callbacks that want to block.
578 640
579If your handler does not plan to block (e.g. simply sends a message to 641If your handler does not plan to block (e.g. simply sends a message to
580another coroutine, or puts some other coroutine into the ready queue), 642another coro, or puts some other coro into the ready queue), there is
581there is no reason to use C<unblock_sub>. 643no reason to use C<unblock_sub>.
582 644
583Note that you also need to use C<unblock_sub> for any other callbacks that 645Note that you also need to use C<unblock_sub> for any other callbacks that
584are indirectly executed by any C-based event loop. For example, when you 646are indirectly executed by any C-based event loop. For example, when you
585use a module that uses L<AnyEvent> (and you use L<Coro::AnyEvent>) and it 647use a module that uses L<AnyEvent> (and you use L<Coro::AnyEvent>) and it
586provides callbacks that are the result of some event callback, then you 648provides callbacks that are the result of some event callback, then you
… …
618 } 680 }
619} 681}
620 682
621=item $cb = Coro::rouse_cb 683=item $cb = Coro::rouse_cb
622 684
623Create and return a "rouse callback". That's a code reference that, when 685Create and return a "rouse callback". That's a code reference that,
624called, will save its arguments and notify the owner coroutine of the 686when called, will remember a copy of its arguments and notify the owner
625callback. 687coro of the callback.
626 688
627See the next function. 689See the next function.
628 690
629=item @args = Coro::rouse_wait [$cb] 691=item @args = Coro::rouse_wait [$cb]
630 692
631Wait for the specified rouse callback (or the last one tht was created in 693Wait for the specified rouse callback (or the last one that was created in
632this coroutine). 694this coro).
633 695
634As soon as the callback is invoked (or when the calback was invoked before 696As soon as the callback is invoked (or when the callback was invoked
635C<rouse_wait>), it will return a copy of the arguments originally passed 697before C<rouse_wait>), it will return the arguments originally passed to
636to the rouse callback. 698the rouse callback.
637 699
638See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example. 700See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
639 701
640=back 702=back
641 703
… …
643 705
6441; 7061;
645 707
646=head1 HOW TO WAIT FOR A CALLBACK 708=head1 HOW TO WAIT FOR A CALLBACK
647 709
648It is very common for a coroutine to wait for some callback to be 710It is very common for a coro to wait for some callback to be
649called. This occurs naturally when you use coroutines in an otherwise 711called. This occurs naturally when you use coro in an otherwise
650event-based program, or when you use event-based libraries. 712event-based program, or when you use event-based libraries.
651 713
652These typically register a callback for some event, and call that callback 714These typically register a callback for some event, and call that callback
653when the event occured. In a coroutine, however, you typically want to 715when the event occured. In a coro, however, you typically want to
654just wait for the event, simplyifying things. 716just wait for the event, simplyifying things.
655 717
656For example C<< AnyEvent->child >> registers a callback to be called when 718For example C<< AnyEvent->child >> registers a callback to be called when
657a specific child has exited: 719a specific child has exited:
658 720
659 my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... }); 721 my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... });
660 722
661But from withina coroutine, you often just want to write this: 723But from within a coro, you often just want to write this:
662 724
663 my $status = wait_for_child $pid; 725 my $status = wait_for_child $pid;
664 726
665Coro offers two functions specifically designed to make this easy, 727Coro offers two functions specifically designed to make this easy,
666C<Coro::rouse_cb> and C<Coro::rouse_wait>. 728C<Coro::rouse_cb> and C<Coro::rouse_wait>.
667 729
668The first function, C<rouse_cb>, generates and returns a callback that, 730The first function, C<rouse_cb>, generates and returns a callback that,
669when invoked, will save it's arguments and notify the coroutine that 731when invoked, will save its arguments and notify the coro that
670created the callback. 732created the callback.
671 733
672The second function, C<rouse_wait>, waits for the callback to be called 734The second function, C<rouse_wait>, waits for the callback to be called
673(by calling C<schedule> to go to sleep) and returns the arguments 735(by calling C<schedule> to go to sleep) and returns the arguments
674originally passed to the callback. 736originally passed to the callback.
… …
689you can roll your own, using C<schedule>: 751you can roll your own, using C<schedule>:
690 752
691 sub wait_for_child($) { 753 sub wait_for_child($) {
692 my ($pid) = @_; 754 my ($pid) = @_;
693 755
694 # store the current coroutine in $current, 756 # store the current coro in $current,
695 # and provide result variables for the closure passed to ->child 757 # and provide result variables for the closure passed to ->child
696 my $current = $Coro::current; 758 my $current = $Coro::current;
697 my ($done, $rstatus); 759 my ($done, $rstatus);
698 760
699 # pass a closure to ->child 761 # pass a closure to ->child
… …
715 777
716=item fork with pthread backend 778=item fork with pthread backend
717 779
718When Coro is compiled using the pthread backend (which isn't recommended 780When Coro is compiled using the pthread backend (which isn't recommended
719but required on many BSDs as their libcs are completely broken), then 781but required on many BSDs as their libcs are completely broken), then
720coroutines will not survive a fork. There is no known workaround except to 782coro will not survive a fork. There is no known workaround except to
721fix your libc and use a saner backend. 783fix your libc and use a saner backend.
722 784
723=item perl process emulation ("threads") 785=item perl process emulation ("threads")
724 786
725This module is not perl-pseudo-thread-safe. You should only ever use this 787This module is not perl-pseudo-thread-safe. You should only ever use this
726module from the same thread (this requirement might be removed in the 788module from the first thread (this requirement might be removed in the
727future to allow per-thread schedulers, but Coro::State does not yet allow 789future to allow per-thread schedulers, but Coro::State does not yet allow
728this). I recommend disabling thread support and using processes, as having 790this). I recommend disabling thread support and using processes, as having
729the windows process emulation enabled under unix roughly halves perl 791the windows process emulation enabled under unix roughly halves perl
730performance, even when not used. 792performance, even when not used.
731 793
732=item coroutine switching not signal safe 794=item coro switching is not signal safe
733 795
734You must not switch to another coroutine from within a signal handler 796You must not switch to another coro from within a signal handler
735(only relevant with %SIG - most event libraries provide safe signals). 797(only relevant with %SIG - most event libraries provide safe signals).
736 798
737That means you I<MUST NOT> call any function that might "block" the 799That means you I<MUST NOT> call any function that might "block" the
738current coroutine - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or 800current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
739anything that calls those. Everything else, including calling C<ready>, 801anything that calls those. Everything else, including calling C<ready>,
740works. 802works.
741 803
742=back 804=back
743 805
… …
748 810
749Debugging: L<Coro::Debug>. 811Debugging: L<Coro::Debug>.
750 812
751Support/Utility: L<Coro::Specific>, L<Coro::Util>. 813Support/Utility: L<Coro::Specific>, L<Coro::Util>.
752 814
753Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, L<Coro::SemaphoreSet>, L<Coro::RWLock>. 815Locking and IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>,
816L<Coro::SemaphoreSet>, L<Coro::RWLock>.
754 817
755IO/Timers: L<Coro::Timer>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::AIO>. 818I/O and Timers: L<Coro::Timer>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::AIO>.
756 819
757Compatibility: L<Coro::LWP>, L<Coro::BDB>, L<Coro::Storable>, L<Coro::Select>. 820Compatibility with other modules: L<Coro::LWP> (but see also L<AnyEvent::HTTP> for
821a better-working alternative), L<Coro::BDB>, L<Coro::Storable>,
822L<Coro::Select>.
758 823
759XS API: L<Coro::MakeMaker>. 824XS API: L<Coro::MakeMaker>.
760 825
761Low level Configuration, Coroutine Environment: L<Coro::State>. 826Low level Configuration, Thread Environment, Continuations: L<Coro::State>.
762 827
763=head1 AUTHOR 828=head1 AUTHOR
764 829
765 Marc Lehmann <schmorp@schmorp.de> 830 Marc Lehmann <schmorp@schmorp.de>
766 http://home.schmorp.de/ 831 http://home.schmorp.de/

Diff Legend

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