[ViewVC] Diff of: cvs/Coro/Coro.pm

Comparing Coro/Coro.pm (file contents):
Revision 1.349 by root, Tue Aug 14 16:51:37 2018 UTC vs.
Revision 1.359 by root, Wed Jul 21 06:40:13 2021 UTC

 =over 4
 =item 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 C<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.
 C<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.
+for some event is alive on its own.
 Another way to create a thread is to call the C<new> constructor with a
 code-reference:
    new Coro sub {
    my $hello_world = $coro->join;
    print $hello_world;
-Another way to terminate is to call C<< Coro::terminate >>, which at any
+Another way to terminate is to call C<< Coro::terminate >>, the
-subroutine call nesting level:
+thread-equivalent of C<exit>, which works at any subroutine call nesting
+level:
    async {
       Coro::terminate "return value 1", "return value 2";
    };
 implements an endless loop, the C<$guard> will not be cleaned up. However,
 since the thread object returned by C<async> is not stored anywhere, the
 thread is initially referenced because it is in the ready queue, when it
 runs it is referenced by C<$Coro::current>, but when it calls C<schedule>,
 it gets C<cancel>ed causing the guard object to be destroyed (see the next
-section), and printing it's message.
+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 leaking the thread,
 or cleaning it up, which brings us to...
 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 it's way, it
+work its way up through all subroutine calls and blocks. On its way, it
 will release all C<my> variables, undo all C<local>'s and free any other
 resources truly local to the thread.
 So, a common way to free resources is to keep them referenced only by my
 variables:
 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
    };
 our $idle;    # idle handler
 our $main;    # main coro
 our $current; # current coro
-our $VERSION = 6.52;
+our $VERSION = 6.57;
 our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait);
 our %EXPORT_TAGS = (
       prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
 );
 automatically get assigned a perl interpreter when they are transferred to.
 =item $state->is_zombie
 Returns true iff the Coro object has been cancelled, i.e.
-it's resources freed because they were C<cancel>'ed, C<terminate>'d,
+its resources freed because they were C<cancel>'ed, C<terminate>'d,
 C<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 called a
 "zombie".
 A thread is in a safe-cancellable state if it either has never been run
 yet, has already been canceled/terminated or otherwise 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
+The first two states are trivial - a thread that has not started or has
 already finished is safe to cancel.
 The last state basically means that the thread isn't currently inside a
 perl callback called from some C function (usually via some XS modules)
 and isn't currently executing inside some C function itself (via Coro's XS
 return once the C<$coro> terminates.
 =item $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 it is joined. The
+that is, after its resources have been freed but before it is joined. The
 callback gets passed the terminate/cancel arguments, if any, and I<must
 not> die, under any circumstances.
 There can be any number of C<on_destroy> callbacks per coro, and there is
 currently no way to remove a callback once added.
 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.
 =item @args = rouse_wait [$cb]
-Wait for the specified rouse callback (or the last one that was created in
+Wait for the specified rouse callback to be invoked (or if the argument is
-this coro).
+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 C<rouse_wait>), it will return the arguments originally passed to
 the rouse callback. In scalar context, that means you get the I<last>
 argument, just as if C<rouse_wait> had a C<return ($a1, $a2, $a3...)>
 statement at the end.
+You are only allowed to wait once for a given rouse callback.
 See the section B<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.
 =back
 =cut
       # some modules have their new predefined in State.xs, some don't
       *{"Coro::$module\::new"} = $old
          if $old;
-      goto &{"Coro::$module\::new"};
+      goto &{"Coro::$module\::new"}
    };
 }
 1;

Diff Legend

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

Comparing Coro/Coro.pm (file contents): Revision 1.349 by root, Tue Aug 14 16:51:37 2018 UTC vs. Revision 1.359 by root, Wed Jul 21 06:40:13 2021 UTC

Diff Legend

Comparing Coro/Coro.pm (file contents):
Revision 1.349 by root, Tue Aug 14 16:51:37 2018 UTC vs.
Revision 1.359 by root, Wed Jul 21 06:40:13 2021 UTC