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

Comparing Coro/Coro.pm (file contents):
Revision 1.296 by root, Thu May 12 23:24:28 2011 UTC vs.
Revision 1.314 by root, Fri Dec 7 23:23:15 2012 UTC

   cede; # yield to coro
   print "3\n";
   cede; # and again
   # use locking
-  use Coro::Semaphore;
   my $lock = new Coro::Semaphore;
   my $locked;
   $lock->down;
   $locked = 1;
    } 1, 2, 3;
 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.
-C<async> will return a coro object - you can store this for future
+C<async> will return a Coro object - you can store this for future
-reference or ignore it, the thread itself will keep a reference to it's
+reference or ignore it - a thread that is running, ready to run or waiting
-thread object - threads are alive on their own.
+for some event is alive on it's own.
 Another way to create a thread is to call the C<new> constructor with a
 code-reference:
    new Coro sub {
 A lot can happen after the coro thread has started running. Quite usually,
 it will not run to the end in one go (because you could use a function
 instead), but it will give up the CPU regularly because it waits for
 external events.
-As long as a coro thread runs, it's coro object is available in the global
+As long as a coro thread runs, its Coro object is available in the global
 variable C<$Coro::current>.
 The low-level way to give up the CPU is to call the scheduler, which
 selects a new coro thread to run:
    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.
+Last not least, a coro thread object that isn't referenced is C<<
+->cancel >>'ed automatically - just like other objects in Perl. This
+is not such a common case, however - a running thread is referencedy by
+C<$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 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:
+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
       # gets freed, so use a guard to ensure it's destruction
       # if we return or die here, the description will be restored
    }
 =item 6. Viva La Zombie Muerte
-Even after a thread has terminated and cleaned up it's resources, the coro
+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. Only in
+object still is there and stores the return values of the thread.
-this state will the coro object be "reference counted" in the normal perl
-sense: the thread code keeps a reference to it when it is active, but not
-after it has terminated.
-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 = 5.372;
+our $VERSION = 6.23;
 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
 To avoid this, it is best to put a suspended coro into the ready queue
 unconditionally, as every synchronisation mechanism must protect itself
 against spurious wakeups, and the one in the Coro family certainly do
 that.
+=item $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.
+=item $state->is_zombie
+Returns true iff the Coro object has been cancelled, i.e.
+it's resources freed because they were C<cancel>'ed, C<terminate>'d,
+C<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 called a
+"zombie".
 =item $is_ready = $coro->is_ready
 Returns true iff the Coro object is in the ready queue. Unless the Coro
 object gets destroyed, it will eventually be scheduled by the scheduler.
 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 it'S thread context, things will
+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
 a thread context, and is not allowed to switch to other threads. On the
 plus side, C<< ->cancel >> will always clean up the thread, no matter
 Wait until the coro terminates and return any values given to the
 C<terminate> or C<cancel> functions. C<join> can be called concurrently
 from multiple threads, and all will be resumed and given the status
 return once the C<$coro> terminates.
-=cut
-sub xjoin {
-   my $self = shift;
-   unless ($self->{_status}) {
-      my $current = $current;
-      push @{$self->{_on_destroy}}, sub {
-         $current->ready;
-         undef $current;
-      };
-      &schedule while $current;
-   }
-   wantarray ? @{$self->{_status}} : $self->{_status}[0]
-}
 =item $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 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.
-=cut
-sub xon_destroy {
-   my ($self, $cb) = @_;
-   push @{ $self->{_on_destroy} }, $cb;
-}
 =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";
       ...
       my ($rpid, $rstatus) = Coro::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.296 by root, Thu May 12 23:24:28 2011 UTC vs. Revision 1.314 by root, Fri Dec 7 23:23:15 2012 UTC

Diff Legend

Comparing Coro/Coro.pm (file contents):
Revision 1.296 by root, Thu May 12 23:24:28 2011 UTC vs.
Revision 1.314 by root, Fri Dec 7 23:23:15 2012 UTC