[ViewVC] Diff of: cvs/Coro/README

Comparing Coro/README (file contents):
Revision 1.27 by root, Fri Dec 25 07:17:12 2009 UTC vs.
Revision 1.28 by root, Sun Feb 13 04:39:15 2011 UTC

         "terminate" or "cancel" functions. "join" can be called concurrently
         from multiple coro, and all will be resumed and given the status
         return once the $coro terminates.
     $coro->on_destroy (\&cb)
-        Registers a callback that is called when this coro gets destroyed,
+        Registers a callback that is called when this coro thread gets
-        but before it is joined. The callback gets passed the terminate
+        destroyed, but before it is joined. The callback gets passed the
-        arguments, if any, and *must not* die, under any circumstances.
+        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.
+        Sets (or gets, if the argument is missing) the priority of the coro
-        Higher priority coro get run before lower priority coro. Priorities
+        thread. Higher priority coro get run before lower priority coros.
-        are small signed integers (currently -4 .. +3), that you can refer
+        Priorities are small signed integers (currently -4 .. +3), that you
-        to using PRIO_xxx constants (use the import tag :prio to get then):
+        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
            # set priority to HIGH
            current->prio (PRIO_HIGH);
-        The idle coro ($Coro::idle) always has a lower priority than any
+        The idle coro thread ($Coro::idle) always has a lower priority than
-        existing coro.
+        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
+        this coro thread. This is just a free-form string you can associate
-        coro.
+        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
         Returns the number of coro that are currently in the ready state,
         i.e. that can be switched to by calling "schedule" directory or
         The reason this function exists is that many event libraries (such
         as the venerable Event module) are not thread-safe (a weaker form of
         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
         and only works when you do not run your own event loop.
     ithreads (for example, that memory or files would be shared), showing
     his lack of understanding of this area - if it is hard to understand for
     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
     secondly, to replace the older, real thread model ("5.005-threads").

Diff Legend

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

Comparing Coro/README (file contents): Revision 1.27 by root, Fri Dec 25 07:17:12 2009 UTC vs. Revision 1.28 by root, Sun Feb 13 04:39:15 2011 UTC

Diff Legend

Comparing Coro/README (file contents):
Revision 1.27 by root, Fri Dec 25 07:17:12 2009 UTC vs.
Revision 1.28 by root, Sun Feb 13 04:39:15 2011 UTC