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

Comparing Coro/Coro.pm (file contents):
Revision 1.308 by root, Fri Apr 13 10:53:24 2012 UTC vs.
Revision 1.321 by root, Sun Feb 2 03:26:06 2014 UTC

    async {
       Coro::terminate "return value 1", "return value 2";
    };
-And yet another way is to C<< ->cancel >> (or C<< ->safe_cancel >>) the
+Yet another way is to C<< ->cancel >> (or C<< ->safe_cancel >>) the coro
-coro thread from another thread:
+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 C<tie> method or an C<AUTOLOAD> for example) is
 safe.
-Lastly, a coro thread object that isn't referenced is C<< ->cancel >>'ed
+Last not least, a coro thread object that isn't referenced is C<<
-automatically - just like other objects in Perl. This is not such a common
+->cancel >>'ed automatically - just like other objects in Perl. This
-case, however - a running thread is referencedy b C<$Coro::current>, a
+is not such a common case, however - a running thread is referencedy by
-thread ready to run is referenced by the ready queue, a thread waiting
+C<$Coro::current>, a thread ready to run is referenced by the ready queue,
-on a lock or semaphore is referenced by being in some wait list and so
+a thread waiting on a lock or semaphore is referenced by being in some
-on. But a thread that isn't in any of those queues gets cancelled:
+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 C<async>
+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.
+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...
 =item 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 C<Guard::guard> function comes in handy for any custom cleanup you
-might want to do (but you cannot switch to other coroutines form those
+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
 =item 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 has
+When there are no other references, it will simply be cleaned up and
-terminated and cleaned up and there arenot other references.
+freed.
-If there are, the Coro object will stay around, and you can call C<<
+If there areany references, the Coro object will stay around, and you
-->join >> as many times as you wish to retrieve the result values:
+can call C<< ->join >> as many times as you wish to retrieve the result
+values:
    async {
       print "hi\n";
       1
    };
 our $idle;    # idle handler
 our $main;    # main coro
 our $current; # current coro
-our $VERSION = 6.08;
+our $VERSION = 6.33;
 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)],
 );
 =over 4
 =item $Coro::main
 This variable stores the Coro object that represents the main
-program. While you cna C<ready> it and do most other things you can do to
+program. While you can C<ready> it and do most other things you can do to
 coro, it is mainly useful to compare again C<$Coro::current>, to see
 whether you are running in the main program or not.
 =cut
 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 I<must
 not> die, under any circumstances.
 There can be any number of C<on_destroy> callbacks per coro, and there is
-no way currently to remove a callback once added.
+currently no way to remove a callback once added.
 =item $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
 coro thread. This is just a free-form string you can associate with a
 coro.
 This method simply sets the C<< $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
+is often preferred to indicate major processing states that can then be
 seen for example in a L<Coro::Debug> session:
    sub my_long_function {
       local $Coro::current->{desc} = "now in my_long_function";
       ...
 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,
-C<Coro::rouse_cb> and C<Coro::rouse_wait>.
+C<rouse_cb> and C<rouse_wait>.
 The first function, C<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 C<rouse_cb> and C<rouse_wait> are not flexible enough,
-you can roll your own, using C<schedule>:
+you can roll your own, using C<schedule> and C<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/Coro.pm (file contents): Revision 1.308 by root, Fri Apr 13 10:53:24 2012 UTC vs. Revision 1.321 by root, Sun Feb 2 03:26:06 2014 UTC

Diff Legend

Comparing Coro/Coro.pm (file contents):
Revision 1.308 by root, Fri Apr 13 10:53:24 2012 UTC vs.
Revision 1.321 by root, Sun Feb 2 03:26:06 2014 UTC