--- Coro/README	2009/12/25 07:17:12	1.27
+++ Coro/README	2011/02/13 04:39:15	1.28
@@ -413,15 +413,19 @@
         return once the $coro terminates.
 
     $coro->on_destroy (\&cb)
-        Registers a callback that is called when this coro gets destroyed,
-        but before it is joined. The callback gets passed the terminate
-        arguments, if any, and *must not* die, under any circumstances.
+        Registers a callback that is called when this coro thread gets
+        destroyed, but before it is joined. The callback gets passed the
+        terminate arguments, if any, and *must not* die, under any
+        circumstances.
+
+        There can be any number of "on_destroy" callbacks per coro.
 
     $oldprio = $coro->prio ($newprio)
-        Sets (or gets, if the argument is missing) the priority of the coro.
-        Higher priority coro get run before lower priority coro. Priorities
-        are small signed integers (currently -4 .. +3), that you can refer
-        to using PRIO_xxx constants (use the import tag :prio to get then):
+        Sets (or gets, if the argument is missing) the priority of the coro
+        thread. Higher priority coro get run before lower priority coros.
+        Priorities are small signed integers (currently -4 .. +3), that you
+        can refer to using PRIO_xxx constants (use the import tag :prio to
+        get then):
 
            PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
                3    >     1     >      0      >    -1    >    -3     >    -4
@@ -429,25 +433,37 @@
            # set priority to HIGH
            current->prio (PRIO_HIGH);
 
-        The idle coro ($Coro::idle) always has a lower priority than any
-        existing coro.
+        The idle coro thread ($Coro::idle) always has a lower priority than
+        any existing coro.
 
         Changing the priority of the current coro will take effect
-        immediately, but changing the priority of coro in the ready queue
+        immediately, but changing the priority of a coro in the ready queue
         (but not running) will only take effect after the next schedule (of
         that coro). This is a bug that will be fixed in some future version.
 
     $newprio = $coro->nice ($change)
         Similar to "prio", but subtract the given value from the priority
-        (i.e. higher values mean lower priority, just as in unix).
+        (i.e. higher values mean lower priority, just as in UNIX's nice
+        command).
 
     $olddesc = $coro->desc ($newdesc)
         Sets (or gets in case the argument is missing) the description for
-        this coro. This is just a free-form string you can associate with a
-        coro.
+        this coro thread. This is just a free-form string you can associate
+        with a coro.
 
         This method simply sets the "$coro->{desc}" member to the given
-        string. You can modify this member directly if you wish.
+        string. You can modify this member directly if you wish, and in
+        fact, this is often preferred to indicate major processing states
+        that cna then be seen for example in a Coro::Debug session:
+
+           sub my_long_function {
+              local $Coro::current->{desc} = "now in my_long_function";
+              ...
+              $Coro::current->{desc} = "my_long_function: phase 1";
+              ...
+              $Coro::current->{desc} = "my_long_function: phase 2";
+              ...
+           }
 
 GLOBAL FUNCTIONS
     Coro::nready
@@ -474,7 +490,8 @@
         reentrancy). This means you must not block within event callbacks,
         otherwise you might suffer from crashes or worse. The only event
         library currently known that is safe to use without "unblock_sub" is
-        EV.
+        EV (but you might still run into deadlocks if all event loops are
+        blocked).
 
         Coro will try to catch you when you block in the event loop
         ("FATAL:$Coro::IDLE blocked itself"), but this is just best effort
@@ -618,7 +635,7 @@
     Chip, it is probably not obvious to everybody).
 
     What follows is an ultra-condensed version of my talk about threads in
-    scripting languages given onthe perl workshop 2009:
+    scripting languages given on the perl workshop 2009:
 
     The so-called "ithreads" were originally implemented for two reasons:
     first, to (badly) emulate unix processes on native win32 perls, and