ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Coro/Coro.pm
Revision: 1.243
Committed: Sat Dec 13 19:18:36 2008 UTC (15 years, 6 months ago) by root
Branch: MAIN
Changes since 1.242: +3 -28 lines
Log Message:
*** empty log message ***

File Contents

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