[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.33 by root, Tue Mar 4 06:13:24 2014 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
         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";
     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.33 by root, Tue Mar 4 06:13:24 2014 UTC

Diff Legend

Comparing Coro/README (file contents):
Revision 1.30 by root, Wed Jun 29 17:58:52 2011 UTC vs.
Revision 1.33 by root, Tue Mar 4 06:13:24 2014 UTC