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

Comparing Coro/Coro.pm (file contents):
Revision 1.321 by root, Sun Feb 2 03:26:06 2014 UTC vs.
Revision 1.356 by root, Mon Mar 16 11:12:52 2020 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.33;
+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)],
 );
 C<async> does. As the coro is being reused, stuff like C<on_destroy>
 will not work in the expected way, unless you call terminate or cancel,
 which somehow defeats the purpose of pooling (but is fine in the
 exceptional case).
-The priority will be reset to C<0> after each run, tracing will be
+The priority will be reset to C<0> after each run, all C<swap_sv> calls
-disabled, the description will be reset and the default output filehandle
+will be undone, tracing will be disabled, the description will be reset
-gets restored, so you can change all these. Otherwise the coro will
+and the default output filehandle gets restored, so you can change all
-be re-used "as-is": most notably if you change other per-coro global
+these. Otherwise the coro will be re-used "as-is": most notably if you
-stuff such as C<$/> you I<must needs> revert that change, which is most
+change other per-coro global stuff such as C<$/> you I<must needs> revert
-simply done by using local as in: C<< local $/ >>.
+that change, which is most simply done by using local as in: C<< local $/
+>>.
 The idle pool size is limited to C<8> idle coros (this can be
 adjusted by changing $Coro::POOL_SIZE), but there can be as many non-idle
 coros as required.
       # at this place, the timezone is Antarctica/South_Pole,
       # without disturbing the TZ of any other coro.
    };
 This can be used to localise about any resource (locale, uid, current
-working directory etc.) to a block, despite the existance of other
+working directory etc.) to a block, despite the existence of other
 coros.
 Another interesting example implements time-sliced multitasking using
 interval timers (this could obviously be optimised, but does the job):
       Coro::on_enter {
          # on entering the thread, we set an VTALRM handler to cede
          $SIG{VTALRM} = sub { cede };
          # and then start the interval timer
          Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01;
       };
       Coro::on_leave {
          # on leaving the thread, we stop the interval timer again
          Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0;
       };
       &{+shift};
    }
    # use like this:
    timeslice {
       # The following is an endless loop that would normally
       # monopolise the process. Since it runs in a timesliced
       # environment, it will regularly cede to other threads.
       while () { }
    };
 =item killall
 Kills/terminates/cancels all coros except the currently running one.
 =item $state->is_new
 Returns true iff this Coro object is "new", i.e. has never been run
 yet. Those states basically consist of only the code reference to call and
 the arguments, but consumes very little other resources. New states will
-automatically get assigned a perl interpreter when they are transfered to.
+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,
 bad things can happen, or if the cancelled thread insists on running
 complicated cleanup handlers that rely on its thread context, things will
 not work.
-Any cleanup code being run (e.g. from C<guard> blocks) will be run without
+Any cleanup code being run (e.g. from C<guard> blocks, destructors and so
-a thread context, and is not allowed to switch to other threads. On the
+on) will be run without a thread context, and is not allowed to switch
+to other threads. A common mistake is to call C<< ->cancel >> from a
+destructor called by die'ing inside the thread to be cancelled for
+example.
-plus side, C<< ->cancel >> will always clean up the thread, no matter
+On the plus side, C<< ->cancel >> will always clean up the thread, no
-what.  If your cleanup code is complex or you want to avoid cancelling a
+matter what.  If your cleanup code is complex or you want to avoid
-C-thread that doesn't know how to clean up itself, it can be better to C<<
+cancelling a C-thread that doesn't know how to clean up itself, it can be
-->throw >> an exception, or use C<< ->safe_cancel >>.
+better to C<< ->throw >> an exception, or use C<< ->safe_cancel >>.
 The arguments to C<< ->cancel >> are not copied, but instead will
 be referenced directly (e.g. if you pass C<$var> and after the call
 change that variable, then you might change the return values passed to
 e.g. C<join>, so don't do that).
 =item $coro->safe_cancel ($arg...)
 Works mostly like C<< ->cancel >>, but is inherently "safer", and
 consequently, can fail with an exception in cases the thread is not in a
-cancellable state.
+cancellable state. Essentially, C<< ->safe_cancel >> is a C<< ->cancel >>
+with extra checks before canceling.
-This method works a bit like throwing an exception that cannot be caught
+It works a bit like throwing an exception that cannot be caught -
-- specifically, it will clean up the thread from within itself, so
+specifically, it will clean up the thread from within itself, so all
-all cleanup handlers (e.g. C<guard> blocks) are run with full thread
+cleanup handlers (e.g. C<guard> blocks) are run with full thread
 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.
 otherwise you might suffer from crashes or worse. The only event library
 currently known that is safe to use without C<unblock_sub> is L<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
+("FATAL: $Coro::idle blocked itself"), but this is just best effort and
 only works when you do not run your own event loop.
 This function allows your callbacks to block by executing them in another
 coro where it is safe to block. One example where blocking is handy
 is when you use the L<Coro::AIO|Coro::AIO> functions to save results to
 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;
 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.
 These typically register a callback for some event, and call that callback
-when the event occured. In a coro, however, you typically want to
+when the event occurred. In a coro, however, you typically want to
 just wait for the event, simplyifying things.
 For example C<< AnyEvent->child >> registers a callback to be called when
 a specific child has exited:
 processes. What makes it so bad is that on non-windows platforms, you can
 actually take advantage of custom hardware for this purpose (as evidenced
 by the forks module, which gives you the (i-) threads API, just much
 faster).
-Sharing data is in the i-threads model is done by transfering data
+Sharing data is in the i-threads model is done by transferring data
 structures between threads using copying semantics, which is very slow -
 shared data simply does not exist. Benchmarks using i-threads which are
 communication-intensive show extremely bad behaviour with i-threads (in
 fact, so bad that Coro, which cannot take direct advantage of multiple
 CPUs, is often orders of magnitude faster because it shares data using
 XS API: L<Coro::MakeMaker>.
 Low level Configuration, Thread Environment, Continuations: L<Coro::State>.
-=head1 AUTHOR
+=head1 AUTHOR/SUPPORT/CONTACT
- Marc Lehmann <schmorp@schmorp.de>
+   Marc A. Lehmann <schmorp@schmorp.de>
- http://home.schmorp.de/
+   http://software.schmorp.de/pkg/Coro.html
 =cut

Diff Legend

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

Comparing Coro/Coro.pm (file contents): Revision 1.321 by root, Sun Feb 2 03:26:06 2014 UTC vs. Revision 1.356 by root, Mon Mar 16 11:12:52 2020 UTC

Diff Legend

Comparing Coro/Coro.pm (file contents):
Revision 1.321 by root, Sun Feb 2 03:26:06 2014 UTC vs.
Revision 1.356 by root, Mon Mar 16 11:12:52 2020 UTC