--- Coro/Coro.pm	2007/04/13 03:57:15	1.120
+++ Coro/Coro.pm	2007/09/21 01:23:58	1.133
@@ -22,8 +22,8 @@
 
 This module collection manages coroutines. Coroutines are similar
 to threads but don't run in parallel at the same time even on SMP
-machines. The specific flavor of coroutine use din this module also
-guarentees you that it will not switch between coroutines unless
+machines. The specific flavor of coroutine used in this module also
+guarantees you that it will not switch between coroutines unless
 necessary, at easily-identified points in your program, so locking and
 parallel access are rarely an issue, making coroutine programming much
 safer than threads programming.
@@ -52,7 +52,7 @@
 our $main;    # main coroutine
 our $current; # current coroutine
 
-our $VERSION = '3.56';
+our $VERSION = '3.7';
 
 our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
 our %EXPORT_TAGS = (
@@ -110,11 +110,13 @@
 is C<$main> (of course).
 
 This variable is B<strictly> I<read-only>. It is provided for performance
-reasons. If performance is not essentiel you are encouraged to use the
+reasons. If performance is not essential you are encouraged to use the
 C<Coro::current> function instead.
 
 =cut
 
+$main->{desc} = "[main::]";
+
 # maybe some other module used Coro::Specific before...
 $main->{specific} = $current->{specific}
    if $current;
@@ -168,7 +170,7 @@
       &schedule;
    }
 };
-
+$manager->desc ("[coro manager]");
 $manager->prio (PRIO_MAX);
 
 # static methods. not really.
@@ -187,10 +189,9 @@
 (usually unused). When the sub returns the new coroutine is automatically
 terminated.
 
-Calling C<exit> in a coroutine will not work correctly, so do not do that.
-
-When the coroutine dies, the program will exit, just as in the main
-program.
+Calling C<exit> in a coroutine will do the same as calling exit outside
+the coroutine. Likewise, when the coroutine dies, the program will exit,
+just as it would in the main program.
 
    # create a new coroutine that just prints its arguments
    async {
@@ -225,25 +226,31 @@
 required.
 
 If you are concerned about pooled coroutines growing a lot because a
-single C<async_pool> used a lot of stackspace you can e.g. C<async_pool {
-terminate }> once per second or so to slowly replenish the pool.
+single C<async_pool> used a lot of stackspace you can e.g. C<async_pool
+{ terminate }> once per second or so to slowly replenish the pool. In
+addition to that, when the stacks used by a handler grows larger than 16kb
+(adjustable with $Coro::MAX_POOL_RSS) it will also exit.
 
 =cut
 
 our $POOL_SIZE = 8;
+our $MAX_POOL_RSS = 16 * 1024;
 our @pool;
 
 sub pool_handler {
    while () {
+      $current->{desc} = "[async_pool]";
+
       eval {
          my ($cb, @arg) = @{ delete $current->{_invoke} or return };
          $cb->(@arg);
       };
       warn $@ if $@;
 
-      last if @pool >= $POOL_SIZE;
-      push @pool, $current;
+      last if @pool >= $POOL_SIZE || $current->rss >= $MAX_POOL_RSS;
 
+      push @pool, $current;
+      $current->{desc} = "[async_pool idle]";
       $current->save (Coro::State::SAVE_DEF);
       $current->prio (0);
       schedule;
@@ -252,7 +259,7 @@
 
 sub async_pool(&@) {
    # this is also inlined into the unlock_scheduler
-   my $coro = (pop @pool or new Coro \&pool_handler);
+   my $coro = (pop @pool) || new Coro \&pool_handler;;
 
    $coro->{_invoke} = [@_];
    $coro->ready;
@@ -280,7 +287,7 @@
          undef $current;
       };
 
-      # call schedule until event occured.
+      # call schedule until event occurred.
       # in case we are woken up for other reasons
       # (current still defined), loop.
       Coro::schedule while $current;
@@ -328,7 +335,7 @@
 called. To make the coroutine run you must first put it into the ready queue
 by calling the ready method.
 
-Calling C<exit> in a coroutine will not work correctly, so do not do that.
+See C<async> for additional discussion.
 
 =cut
 
@@ -461,7 +468,7 @@
 =item Coro::nready
 
 Returns the number of coroutines that are currently in the ready state,
-i.e. that can be swicthed to. The value C<0> means that the only runnable
+i.e. that can be switched to. The value C<0> means that the only runnable
 coroutine is the currently running one, so C<cede> would have no effect,
 and C<schedule> would cause a deadlock unless there is an idle handler
 that wakes up some coroutines.
@@ -507,7 +514,7 @@
 immediately without blocking, returning nothing, while the original code
 ref will be called (with parameters) from within its own coroutine.
 
-The reason this fucntion exists is that many event libraries (such as the
+The reason this function exists is that many event libraries (such as the
 venerable L<Event|Event> module) are not coroutine-safe (a weaker form
 of thread-safety). This means you must not block within event callbacks,
 otherwise you might suffer from crashes or worse.
@@ -528,7 +535,7 @@
 # to reduce pressure on the coro pool (because most callbacks
 # return immediately and can be reused) and because we cannot cede
 # inside an event callback.
-our $unblock_scheduler = async {
+our $unblock_scheduler = new Coro sub {
    while () {
       while (my $cb = pop @unblock_queue) {
          # this is an inlined copy of async_pool
@@ -541,6 +548,7 @@
       schedule; # sleep well
    }
 };
+$unblock_scheduler->desc ("[unblock_sub scheduler]");
 
 sub unblock_sub(&) {
    my $cb = shift;
@@ -563,7 +571,7 @@
    destruction. very bad things might happen otherwise (usually segfaults).
 
  - this module is not thread-safe. You should only ever use this module
-   from the same thread (this requirement might be losened in the future
+   from the same thread (this requirement might be loosened in the future
    to allow per-thread schedulers, but Coro::State does not yet allow
    this).