[ViewVC] Diff of: cvs/Coro/README

Comparing Coro/README (file contents):
Revision 1.39 by root, Fri Jul 14 13:14:32 2017 UTC vs.
Revision 1.42 by root, Wed Jul 29 13:09:19 2020 UTC

 CORO THREAD LIFE CYCLE
     During the long and exciting (or not) life of a coro thread, it goes
     through a number of states:
     1. Creation
-        The first thing in the life of a coro thread is it's creation -
+        The first thing in the life of a coro thread is its creation -
         obviously. The typical way to create a thread is to call the "async
         BLOCK" function:
            async {
               # thread code goes here
         This creates a new coro thread and puts it into the ready queue,
         meaning it will run as soon as the CPU is free for it.
         "async" will return a Coro object - you can store this for future
         reference or ignore it - a thread that is running, ready to run or
-        waiting for some event is alive on it's own.
+        waiting for some event is alive on its own.
         Another way to create a thread is to call the "new" constructor with
         a code-reference:
            new Coro sub {
         implements an endless loop, the $guard will not be cleaned up.
         However, since the thread object returned by "async" is not stored
         anywhere, the thread is initially referenced because it is in the
         ready queue, when it runs it is referenced by $Coro::current, but
         when it calls "schedule", it gets "cancel"ed causing the guard
-        object to be destroyed (see the next section), and printing it's
+        object to be destroyed (see the next section), and printing its
         message.
         If this seems a bit drastic, remember that this only happens when
         nothing references the thread anymore, which means there is no way
         to further execute it, ever. The only options at this point are
     5. Cleanup
         Threads will allocate various resources. Most but not all will be
         returned when a thread terminates, during clean-up.
         Cleanup is quite similar to throwing an uncaught exception: perl
-        will work it's way up through all subroutine calls and blocks. On
+        will work its way up through all subroutine calls and blocks. On its
-        it's way, it will release all "my" variables, undo all "local"'s and
+        way, it will release all "my" variables, undo all "local"'s and free
-        free any other resources truly local to the thread.
+        any other resources truly local to the thread.
         So, a common way to free resources is to keep them referenced only
         by my variables:
            async {
         those code blocks):
            async {
               my $window = new Gtk2::Window "toplevel";
               # The window will not be cleaned up automatically, even when $window
-              # gets freed, so use a guard to ensure it's destruction
+              # gets freed, so use a guard to ensure its destruction
               # in case of an error:
               my $window_guard = Guard::guard { $window->destroy };
               # we are safe here
            };
         call and the arguments, but consumes very little other resources.
         New states will automatically get assigned a perl interpreter when
         they are transferred to.
     $state->is_zombie
-        Returns true iff the Coro object has been cancelled, i.e. it's
+        Returns true iff the Coro object has been cancelled, i.e. its
         resources freed because they were "cancel"'ed, "terminate"'d,
         "safe_cancel"'ed or simply went out of scope.
         The name "zombie" stems from UNIX culture, where a process that has
         exited and only stores and exit status and no other resources is
     $is_suspended = $coro->is_suspended
         Returns true iff this Coro object has been suspended. Suspended
         Coros will not ever be scheduled.
-    $coro->cancel (arg...)
+    $coro->cancel ($arg...)
-        Terminates the given Coro thread and makes it return the given
+        Terminate the given Coro thread and make it return the given
         arguments as status (default: an empty list). Never returns if the
         Coro is the current Coro.
         This is a rather brutal way to free a coro, with some limitations -
         if the thread is inside a C callback that doesn't expect to be
         context and can block if they wish. The downside is that there is no
         guarantee that the thread can be cancelled when you call this
         method, and therefore, it might fail. It is also considerably slower
         than "cancel" or "terminate".
-        A thread is in a safe-cancellable state if it either hasn't been run
+        A thread is in a safe-cancellable state if it either has never been
+        run yet, has already been canceled/terminated or otherwise
-        yet, or it has no C context attached and is inside an SLF function.
+        destroyed, or has no C context attached and is inside an SLF
+        function.
+        The first two states are trivial - a thread that hasnot started or
+        has already finished is safe to cancel.
-        The latter two basically mean that the thread isn't currently inside
+        The last state basically means that the thread isn't currently
-        a perl callback called from some C function (usually via some XS
+        inside a perl callback called from some C function (usually via some
-        modules) and isn't currently executing inside some C function itself
+        XS modules) and isn't currently executing inside some C function
-        (via Coro's XS API).
+        itself (via Coro's XS API).
         This call returns true when it could cancel the thread, or croaks
         with an error otherwise (i.e. it either returns true or doesn't
         return at all).
         from multiple threads, 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 thread gets
-        destroyed, that is, after it's resources have been freed but before
+        destroyed, that is, after its resources have been freed but before
         it is joined. The callback gets passed the terminate/cancel
         arguments, if any, and *must not* die, under any circumstances.
         There can be any number of "on_destroy" callbacks per coro, and
         there is currently no way to remove a callback once added.
     $cb = rouse_cb
         Create and return a "rouse callback". That's a code reference that,
         when called, will remember a copy of its arguments and notify the
         owner coro of the callback.
+        Only the first invocation will store agruments and signal any waiter
+        - further calls will effectively be ignored, but it is ok to try.
-        See the next function.
+        Also see the next function.
     @args = rouse_wait [$cb]
-        Wait for the specified rouse callback (or the last one that was
+        Wait for the specified rouse callback to be invoked (or if the
-        created in this coro).
+        argument is missing, use the most recently created callback in the
+        current coro).
         As soon as the callback is invoked (or when the callback was invoked
         before "rouse_wait"), it will return the arguments originally passed
         to the rouse callback. In scalar context, that means you get the
         *last* argument, just as if "rouse_wait" had a "return ($a1, $a2,
         $a3...)" statement at the end.
+        You are only allowed to wait once for a given rouse callback.
         See the section HOW TO WAIT FOR A CALLBACK for an actual usage
         example.
+        As of Coro 6.57, you can reliably wait for a rouse callback in a
+        different thread than from where it was created.
 HOW TO WAIT FOR A CALLBACK
     It is very common for a coro to wait for some callback to be called.
     This occurs naturally when you use coro in an otherwise event-based
     program, or when you use event-based libraries.

Diff Legend

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

Comparing Coro/README (file contents): Revision 1.39 by root, Fri Jul 14 13:14:32 2017 UTC vs. Revision 1.42 by root, Wed Jul 29 13:09:19 2020 UTC

Diff Legend

Comparing Coro/README (file contents):
Revision 1.39 by root, Fri Jul 14 13:14:32 2017 UTC vs.
Revision 1.42 by root, Wed Jul 29 13:09:19 2020 UTC