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

Comparing Coro/Coro.pm (file contents):
Revision 1.346 by root, Fri Jul 14 23:20:07 2017 UTC vs.
Revision 1.354 by root, Thu Nov 14 14:19:00 2019 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 {
 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.513;
+our $VERSION = 6.55;
 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".
 =item $is_suspended = $coro->is_suspended
 Returns true iff this Coro object has been suspended. Suspended Coros will
 not ever be scheduled.
-=item $coro->cancel (arg...)
+=item $coro->cancel ($arg...)
-Terminates the given Coro thread and makes it return the given arguments as
+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 canceled,
 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 C<cancel> or
 C<terminate>.
-A thread is in a safe-cancellable state if it either hasn't been run yet,
+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
-or it has no C context attached and is inside an SLF function.
+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 a
+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
 API).
 This call returns true when it could cancel the thread, or croaks with an
 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.
+When the callback is invoked multiple times, only the arguments passed on
+the first call will be stored.
-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
 this coro).
       # 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.346 by root, Fri Jul 14 23:20:07 2017 UTC vs. Revision 1.354 by root, Thu Nov 14 14:19:00 2019 UTC

Diff Legend

Comparing Coro/Coro.pm (file contents):
Revision 1.346 by root, Fri Jul 14 23:20:07 2017 UTC vs.
Revision 1.354 by root, Thu Nov 14 14:19:00 2019 UTC