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

Comparing Coro/Coro.pm (file contents):
Revision 1.294 by root, Fri May 6 21:15:17 2011 UTC vs.
Revision 1.349 by root, Tue Aug 14 16:51:37 2018 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;
    };
-   $coro->cancel; # an also accept values for ->join to retrieve
+   $coro->cancel; # also accepts values for ->join to retrieve
-Cancellation I<can> be dangerous - it's a bit like calling C<exit>
+Cancellation I<can> be dangerous - it's a bit like calling C<exit> without
-without actually exiting, and might leave C libraries and XS modules in
+actually exiting, and might leave C libraries and XS modules in a weird
-a weird state. Unlike other thread implementations, however, Coro is
+state. Unlike other thread implementations, however, Coro is exceptionally
-exceptionally safe with regards to cancellation, as perl will always be
+safe with regards to cancellation, as perl will always be in a consistent
-in a consistent state, and for those cases where you want to do truly
+state, and for those cases where you want to do truly marvellous things
-marvellous things with your coro while it is being cancelled, there is
+with your coro while it is being cancelled - that is, make sure all
+cleanup code is executed from the thread being cancelled - there is even a
-even a C<< ->safe_cancel >> method.
+C<< ->safe_cancel >> method.
 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.52;
 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
 C<async> does. As the coro is being reused, stuff like C<on_destroy>
 will not work in the expected way, unless you call terminate or cancel,
 which somehow defeats the purpose of pooling (but is fine in the
 exceptional case).
-The priority will be reset to C<0> after each run, tracing will be
+The priority will be reset to C<0> after each run, all C<swap_sv> calls
-disabled, the description will be reset and the default output filehandle
+will be undone, tracing will be disabled, the description will be reset
-gets restored, so you can change all these. Otherwise the coro will
+and the default output filehandle gets restored, so you can change all
-be re-used "as-is": most notably if you change other per-coro global
+these. Otherwise the coro will be re-used "as-is": most notably if you
-stuff such as C<$/> you I<must needs> revert that change, which is most
+change other per-coro global stuff such as C<$/> you I<must needs> revert
-simply done by using local as in: C<< local $/ >>.
+that change, which is most simply done by using local as in: C<< local $/
+>>.
 The idle pool size is limited to C<8> idle coros (this can be
 adjusted by changing $Coro::POOL_SIZE), but there can be as many non-idle
 coros as required.
       # at this place, the timezone is Antarctica/South_Pole,
       # without disturbing the TZ of any other coro.
    };
 This can be used to localise about any resource (locale, uid, current
-working directory etc.) to a block, despite the existance of other
+working directory etc.) to a block, despite the existence of other
 coros.
 Another interesting example implements time-sliced multitasking using
 interval timers (this could obviously be optimised, but does the job):
       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.
 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 transferred 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.
 =item $is_suspended = $coro->is_suspended
 Returns true iff this Coro object has been suspended. Suspended Coros will
 not ever be scheduled.
-=item $coro->cancel (arg...)
+=item $coro->cancel ($arg...)
-Terminates the given Coro thread and makes it return the given arguments as
+Terminate the given Coro thread and make it return the given arguments as
 status (default: an empty list). Never returns if the Coro is the
 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.
-Sometimes it is safer to C<< ->throw >> an exception, or use C<<
+Any cleanup code being run (e.g. from C<guard> blocks, destructors and so
-->safe_cancel >>.
+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.
-The arguments are not copied, but instead will be referenced directly
+On the plus side, C<< ->cancel >> will always clean up the thread, no
-(e.g. if you pass C<$var> and after the call change that variable, then
+matter what.  If your cleanup code is complex or you want to avoid
-you might change the return values passed to e.g. C<join>, so don't do
+cancelling a C-thread that doesn't know how to clean up itself, it can be
-that).
+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).
 The resources of the Coro are usually freed (or destructed) before this
 call returns, but this can be delayed for an indefinite amount of time, as
 in some cases the manager thread has to run first to actually destruct the
 Coro object.
 =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 all
+specifically, it will clean up the thread from within itself, so all
-cleanup handlers (e.g. C<guard> blocks) are run with full thread context
+cleanup handlers (e.g. C<guard> blocks) are run with full thread
-and can block if they wish.
+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>.
-A thread is safe-cancellable if it either hasn't been run yet, or
+A thread is in a safe-cancellable state if it either has never been run
+yet, has already been canceled/terminated or otherwise destroyed, or has
-it has no C context attached and is inside an SLF function.
+no C context attached and is inside an SLF function.
+The first two states are trivial - a thread that hasnot started or has
+already finished is safe to cancel.
-The latter two basically mean that the thread isn't currently inside a
+The last state basically means that the thread isn't currently inside a
-perl callback called from some C function (usually XS modules) and isn't
+perl callback called from some C function (usually via some XS modules)
-currently inside some C function itself.
+and isn't currently executing inside some C function itself (via Coro's XS
+API).
-This call always returns true when it could cancel the thread, or croaks
+This call returns true when it could cancel the thread, or croaks with an
-with an error otherwise, so you can write things like this:
+error otherwise (i.e. it either returns true or doesn't return at all).
+Why the weird interface? Well, there are two common models on how and
+when to cancel things. In the first, you have the expectation that your
+coro thread can be cancelled when you want to cancel it - if the thread
+isn't cancellable, this would be a bug somewhere, so C<< ->safe_cancel >>
+croaks to notify of the bug.
+In the second model you sometimes want to ask nicely to cancel a thread,
+but if it's not a good time, well, then don't cancel. This can be done
+relatively easy like this:
    if (! eval { $coro->safe_cancel }) {
       warn "unable to cancel thread: $@";
    }
+However, what you never should do is first try to cancel "safely" and
+if that fails, cancel the "hard" way with C<< ->cancel >>. That makes
+no sense: either you rely on being able to execute cleanup code in your
+thread context, or you don't. If you do, then C<< ->safe_cancel >> is the
+only way, and if you don't, then C<< ->cancel >> is always faster and more
+direct.
 =item $coro->schedule_to
 Puts the current coro to sleep (like C<Coro::schedule>), but instead
 of continuing with the next coro from the ready queue, always switch to
 inside the coro at the next convenient point in time. Otherwise
 clears the exception object.
 Coro will check for the exception each time a schedule-like-function
 returns, i.e. after each C<schedule>, C<cede>, C<< Coro::Semaphore->down
->>, C<< Coro::Handle->readable >> and so on. Most of these functions
+>>, C<< Coro::Handle->readable >> and so on. Most of those functions (all
-detect this case and return early in case an exception is pending.
+that are part of Coro itself) detect this case and return early in case an
+exception is pending.
 The exception object will be thrown "as is" with the specified scalar in
 C<$@>, i.e. if it is a string, no line number or newline will be appended
 (unlike with C<die>).
-This can be used as a softer means than C<cancel> to ask a coro to
+This can be used as a softer means than either C<cancel> or C<safe_cancel
-end itself, although there is no guarantee that the exception will lead to
+>to ask a coro to end itself, although there is no guarantee that the
-termination, and if the exception isn't caught it might well end the whole
+exception will lead to termination, and if the exception isn't caught it
-program.
+might well end the whole program.
 You might also think of C<throw> as being the moral equivalent of
 C<kill>ing a coro with a signal (in this case, a scalar).
 =item $coro->join
 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.
+currently no way 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
 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";
       ...
 otherwise you might suffer from crashes or worse. The only event library
 currently known that is safe to use without C<unblock_sub> is L<EV> (but
 you might still run into deadlocks if all event loops are blocked).
 Coro will try to catch you when you block in the event loop
-("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and
+("FATAL: $Coro::idle blocked itself"), but this is just best effort and
 only works when you do not run your own event loop.
 This function allows your callbacks to block by executing them in another
 coro where it is safe to block. One example where blocking is handy
 is when you use the L<Coro::AIO|Coro::AIO> functions to save results to
 It is very common for a coro to wait for some callback to be
 called. This occurs naturally when you use coro in an otherwise
 event-based program, or when you use event-based libraries.
 These typically register a callback for some event, and call that callback
-when the event occured. In a coro, however, you typically want to
+when the event occurred. In a coro, however, you typically want to
 just wait for the event, simplyifying things.
 For example C<< AnyEvent->child >> registers a callback to be called when
 a specific child has exited:
 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;
 module from the first thread (this requirement might be removed in the
 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>
 processes. What makes it so bad is that on non-windows platforms, you can
 actually take advantage of custom hardware for this purpose (as evidenced
 by the forks module, which gives you the (i-) threads API, just much
 faster).
-Sharing data is in the i-threads model is done by transfering data
+Sharing data is in the i-threads model is done by transferring data
 structures between threads using copying semantics, which is very slow -
 shared data simply does not exist. Benchmarks using i-threads which are
 communication-intensive show extremely bad behaviour with i-threads (in
 fact, so bad that Coro, which cannot take direct advantage of multiple
 CPUs, is often orders of magnitude faster because it shares data using
 XS API: L<Coro::MakeMaker>.
 Low level Configuration, Thread Environment, Continuations: L<Coro::State>.
-=head1 AUTHOR
+=head1 AUTHOR/SUPPORT/CONTACT
- Marc Lehmann <schmorp@schmorp.de>
+   Marc A. Lehmann <schmorp@schmorp.de>
- http://home.schmorp.de/
+   http://software.schmorp.de/pkg/Coro.html
 =cut

Diff Legend

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

Comparing Coro/Coro.pm (file contents): Revision 1.294 by root, Fri May 6 21:15:17 2011 UTC vs. Revision 1.349 by root, Tue Aug 14 16:51:37 2018 UTC

Diff Legend

Comparing Coro/Coro.pm (file contents):
Revision 1.294 by root, Fri May 6 21:15:17 2011 UTC vs.
Revision 1.349 by root, Tue Aug 14 16:51:37 2018 UTC