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

Comparing Coro/Coro.pm (file contents):
Revision 1.295 by root, Tue May 10 19:55:48 2011 UTC vs.
Revision 1.305 by root, Thu Aug 4 19:37:58 2011 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:
 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
+automatically - just like other objects in Perl. This is not such a common
+case, however - a running thread is referencedy b 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.
 =item 5. Cleanup
 Threads will allocate various resources. Most but not all will be returned
 when a thread terminates, during clean-up.
       # if we reutrn, 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 form 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
+The means the Coro object gets freed automatically when the thread has
 terminated and cleaned up and there arenot other references.
-If there are, the coro object will stay around, and you can call C<<
+If there are, the Coro object will stay around, and you 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.05;
 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)],
 );
 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 join {
-   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 on_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
 future to allow per-thread schedulers, but Coro::State does not yet allow
 this). I recommend disabling thread support and using processes, as having
 the windows process emulation enabled under unix roughly halves perl
 performance, even when not used.
+Attempts to use threads created in another emulated process will crash
+("cleanly", with a null pointer exception).
 =item coro switching is not signal safe
 You must not switch to another coro from within a signal handler (only
 relevant with %SIG - most event libraries provide safe signals), I<unless>
 you are sure you are not interrupting a Coro function.

Diff Legend

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

Comparing Coro/Coro.pm (file contents): Revision 1.295 by root, Tue May 10 19:55:48 2011 UTC vs. Revision 1.305 by root, Thu Aug 4 19:37:58 2011 UTC

Diff Legend

Comparing Coro/Coro.pm (file contents):
Revision 1.295 by root, Tue May 10 19:55:48 2011 UTC vs.
Revision 1.305 by root, Thu Aug 4 19:37:58 2011 UTC