[ViewVC] Diff of: cvs/Coro/README

Comparing Coro/README (file contents):
Revision 1.30 by root, Wed Jun 29 17:58:52 2011 UTC vs.
Revision 1.35 by root, Wed Feb 11 19:30:34 2015 UTC

            async {
               Coro::terminate "return value 1", "return value 2";
            };
-        And yet another way is to "->cancel" (or "->safe_cancel") the coro
+        Yet another way is to "->cancel" (or "->safe_cancel") the coro
         thread from another thread:
            my $coro = async {
               exit 1;
            };
         So, cancelling a thread that runs in an XS event loop might not be
         the best idea, but any other combination that deals with perl only
         (cancelling when a thread is in a "tie" method or an "AUTOLOAD" for
         example) is safe.
-        Lastly, a coro thread object that isn't referenced is "->cancel"'ed
+        Last not least, a coro thread object that isn't referenced is
-        automatically - just like other objects in Perl. This is not such a
+        "->cancel"'ed automatically - just like other objects in Perl. This
-        common case, however - a running thread is referencedy b
+        is not such a common case, however - a running thread is referencedy
-        $Coro::current, a thread ready to run is referenced by the ready
+        by $Coro::current, a thread ready to run is referenced by the ready
         queue, a thread waiting on a lock or semaphore is referenced by
         being in some wait list and so on. But a thread that isn't in any of
         those queues gets cancelled:
            async {
               schedule; # cede to other coros, don't go into the ready queue
            };
            cede;
            # now the async above is destroyed, as it is not referenced by anything.
+        A slightly embellished example might make it clearer:
+           async {
+              my $guard = Guard::guard { print "destroyed\n" };
+              schedule while 1;
+           };
+           cede;
+        Superficially one might not expect any output - since the "async"
+        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
+        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...
     5. Cleanup
         Threads will allocate various resources. Most but not all will be
         returned when a thread terminates, during clean-up.
            my $sem = new Coro::Semaphore;
            async {
               my $lock_guard = $sem->guard;
-              # if we reutrn, or die or get cancelled, here,
+              # if we return, or die or get cancelled, here,
               # then the semaphore will be "up"ed.
            };
         The "Guard::guard" function comes in handy for any custom cleanup
-        you might want to do (but you cannot switch to other coroutines form
+        you might want to do (but you cannot switch to other coroutines from
         those code blocks):
            async {
               my $window = new Gtk2::Window "toplevel";
               # The window will not be cleaned up automatically, even when $window
     6. Viva La Zombie Muerte
         Even after a thread has terminated and cleaned up its resources, the
         Coro object still is there and stores the return values of the
         thread.
-        The means the Coro object gets freed automatically when the thread
+        When there are no other references, it will simply be cleaned up and
-        has terminated and cleaned up and there arenot other references.
+        freed.
-        If there are, the Coro object will stay around, and you can call
+        If there areany references, the Coro object will stay around, and
-        "->join" as many times as you wish to retrieve the result values:
+        you can call "->join" as many times as you wish to retrieve the
+        result values:
            async {
               print "hi\n";
               1
            };
            };
 GLOBAL VARIABLES
     $Coro::main
         This variable stores the Coro object that represents the main
-        program. While you cna "ready" it and do most other things you can
+        program. While you can "ready" it and do most other things you can
         do to coro, it is mainly useful to compare again $Coro::current, to
         see whether you are running in the main program or not.
     $Coro::current
         The Coro object representing the current coro (the last coro that
               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
         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
         yet, or it has no C context attached and is inside an SLF function.
         The latter two basically mean that the thread isn't currently inside
         destroyed, that is, after it's 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
         with a coro.
         This method simply sets the "$coro->{desc}" member to the given
         string. You can modify this member directly if you wish, and in
         fact, this is often preferred to indicate major processing states
-        that cna then be seen for example in a Coro::Debug session:
+        that can then be seen for example in a Coro::Debug session:
            sub my_long_function {
               local $Coro::current->{desc} = "now in my_long_function";
               ...
               $Coro::current->{desc} = "my_long_function: phase 1";
         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
-        ("FATAL:$Coro::IDLE blocked itself"), but this is just best effort
+        ("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 Coro::AIO functions to save results to
     But from within a coro, you often just want to write this:
        my $status = wait_for_child $pid;
     Coro offers two functions specifically designed to make this easy,
-    "Coro::rouse_cb" and "Coro::rouse_wait".
+    "rouse_cb" and "rouse_wait".
     The first function, "rouse_cb", generates and returns a callback that,
     when invoked, will save its arguments and notify the coro that created
     the callback.
     function mentioned above:
        sub wait_for_child($) {
           my ($pid) = @_;
-          my $watcher = AnyEvent->child (pid => $pid, cb => Coro::rouse_cb);
+          my $watcher = AnyEvent->child (pid => $pid, cb => rouse_cb);
-          my ($rpid, $rstatus) = Coro::rouse_wait;
+          my ($rpid, $rstatus) = rouse_wait;
           $rstatus
        }
     In the case where "rouse_cb" and "rouse_wait" are not flexible enough,
-    you can roll your own, using "schedule":
+    you can roll your own, using "schedule" and "ready":
        sub wait_for_child($) {
           my ($pid) = @_;
           # store the current coro in $current,
           my ($done, $rstatus);
           # pass a closure to ->child
           my $watcher = AnyEvent->child (pid => $pid, cb => sub {
              $rstatus = $_[1]; # remember rstatus
-             $done = 1; # mark $rstatus as valud
+             $done = 1;        # mark $rstatus as valid
+             $current->ready;  # wake up the waiting thread
           });
           # wait until the closure has been called
           schedule while !$done;

Diff Legend

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

Comparing Coro/README (file contents): Revision 1.30 by root, Wed Jun 29 17:58:52 2011 UTC vs. Revision 1.35 by root, Wed Feb 11 19:30:34 2015 UTC

Diff Legend

Comparing Coro/README (file contents):
Revision 1.30 by root, Wed Jun 29 17:58:52 2011 UTC vs.
Revision 1.35 by root, Wed Feb 11 19:30:34 2015 UTC