[ViewVC] Diff of: cvs/Coro/README

Comparing Coro/README (file contents):
Revision 1.32 by root, Wed Mar 6 06:00:08 2013 UTC vs.
Revision 1.41 by root, Fri Aug 23 08:01:13 2019 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
            };
         program, as "async" does. As the coro is being reused, stuff like
         "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 0 after each run, tracing will be
+        The priority will be reset to 0 after each run, all "swap_sv" calls
-        disabled, the description will be reset and the default output
+        will be undone, tracing will be disabled, the description will be
-        filehandle gets restored, so you can change all these. Otherwise the
+        reset and the default output filehandle gets restored, so you can
-        coro will be re-used "as-is": most notably if you change other
+        change all these. Otherwise the coro will be re-used "as-is": most
-        per-coro global stuff such as $/ you *must needs* revert that
+        notably if you change other per-coro global stuff such as $/ you
-        change, which is most simply done by using local as in: "local $/".
+        *must needs* revert that change, which is most simply done by using
+        local as in: "local $/".
         The idle pool size is limited to 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
+        current 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
     $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.
+        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
         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 "guard" blocks) will be run
+        Any cleanup code being run (e.g. from "guard" blocks, destructors
-        without a thread context, and is not allowed to switch to other
+        and so on) will be run without a thread context, and is not allowed
+        to switch to other threads. A common mistake is to call "->cancel"
+        from a destructor called by die'ing inside the thread to be
+        cancelled for example.
-        threads. On the plus side, "->cancel" will always clean up the
+        On the plus side, "->cancel" will always clean up the thread, no
-        thread, no matter what. If your cleanup code is complex or you want
+        matter what. If your cleanup code is complex or you want to avoid
-        to avoid cancelling a C-thread that doesn't know how to clean up
+        cancelling a C-thread that doesn't know how to clean up itself, it
-        itself, it can be better to "->throw" an exception, or use
+        can be better to "->throw" an exception, or use "->safe_cancel".
-        "->safe_cancel".
         The arguments to "->cancel" are not copied, but instead will be
         referenced directly (e.g. if you pass $var and after the call change
         that variable, then you might change the return values passed to
         e.g. "join", so don't do that).
         actually destruct the Coro object.
     $coro->safe_cancel ($arg...)
         Works mostly like "->cancel", but is inherently "safer", and
         consequently, can fail with an exception in cases the thread is not
-        in a cancellable state.
+        in a cancellable state. Essentially, "->safe_cancel" is a "->cancel"
+        with extra checks before canceling.
-        This method works a bit like throwing an exception that cannot be
+        It works a bit like throwing an exception that cannot be caught -
-        caught - specifically, it will clean up the thread from within
+        specifically, it will clean up the thread from within itself, so all
-        itself, so all cleanup handlers (e.g. "guard" blocks) are run with
+        cleanup handlers (e.g. "guard" blocks) are run with full thread
-        full thread context and can block if they wish. The downside is that
+        context and can block if they wish. The downside is that there is no
-        there is no guarantee that the thread can be cancelled when you call
+        guarantee that the thread can be cancelled when you call this
-        this method, and therefore, it might fail. It is also considerably
+        method, and therefore, it might fail. It is also considerably slower
-        slower than "cancel" or "terminate".
+        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 no way currently to remove a callback once added.
+        there is currently no way to remove a callback once added.
     $oldprio = $coro->prio ($newprio)
         Sets (or gets, if the argument is missing) the priority of the coro
         thread. Higher priority coro get run before lower priority coros.
         Priorities are small signed integers (currently -4 .. +3), that you
         otherwise you might suffer from crashes or worse. The only event
         library currently known that is safe to use without "unblock_sub" is
         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
+        Coro will try to catch you when you block in the event loop ("FATAL:
-        ("FATAL:$Coro::IDLE blocked itself"), but this is just best effort
+        $Coro::idle blocked itself"), but this is just best effort and only
-        and only works when you do not run your own event loop.
+        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 Coro::AIO functions to save results to
         disk, for example.
     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
+    callback when the event occurred. In a coro, however, you typically want
     to just wait for the event, simplyifying things.
     For example "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: Coro::MakeMaker.
     Low level Configuration, Thread Environment, Continuations: Coro::State.
-AUTHOR
+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

Diff Legend

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

Comparing Coro/README (file contents): Revision 1.32 by root, Wed Mar 6 06:00:08 2013 UTC vs. Revision 1.41 by root, Fri Aug 23 08:01:13 2019 UTC

Diff Legend

Comparing Coro/README (file contents):
Revision 1.32 by root, Wed Mar 6 06:00:08 2013 UTC vs.
Revision 1.41 by root, Fri Aug 23 08:01:13 2019 UTC