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

Comparing Coro/Coro.pm (file contents):
Revision 1.305 by root, Thu Aug 4 19:37:58 2011 UTC vs.
Revision 1.327 by root, Sun Jun 1 22:00:45 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.05;
+our $VERSION = 6.39;
 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
       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.
 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>.
 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.305 by root, Thu Aug 4 19:37:58 2011 UTC vs. Revision 1.327 by root, Sun Jun 1 22:00:45 2014 UTC

Diff Legend

Comparing Coro/Coro.pm (file contents):
Revision 1.305 by root, Thu Aug 4 19:37:58 2011 UTC vs.
Revision 1.327 by root, Sun Jun 1 22:00:45 2014 UTC