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

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.220 by root, Sun Nov 16 11:12:57 2008 UTC vs.
Revision 1.237 by root, Sat Nov 22 16:37:11 2008 UTC

 =head1 NAME
-Coro - coroutine process abstraction
+Coro - real threads in perl
 =head1 SYNOPSIS
   use Coro;
   $locked = 1;
   $lock->up;
 =head1 DESCRIPTION
-This module collection manages coroutines. Coroutines are similar to
+For a tutorial-style introduction, please read the L<Coro::Intro>
-threads but don't (in general) run in parallel at the same time even
+manpage. This manpage mainly contains reference information.
-on SMP machines. The specific flavor of coroutine used in this module
-also guarantees you that it will not switch between coroutines unless
-necessary, at easily-identified points in your program, so locking and
-parallel access are rarely an issue, making coroutine programming much
-safer and easier than threads programming.
-Unlike a normal perl program, however, coroutines allow you to have
+This module collection manages coroutines, that is, cooperative
-multiple running interpreters that share data, which is especially useful
+threads. Coroutines are similar to kernel threads but don't (in general)
-to code pseudo-parallel processes and for event-based programming, such as
+run in parallel at the same time even on SMP machines. The specific flavor
-multiple HTTP-GET requests running concurrently. See L<Coro::AnyEvent> to
+of coroutine used in this module also guarantees you that it will not
-learn more.
+switch between coroutines unless necessary, at easily-identified points
+in your program, so locking and parallel access are rarely an issue,
+making coroutine programming much safer and easier than using other thread
+models.
-Coroutines are also useful because Perl has no support for threads (the so
+Unlike the so-called "Perl threads" (which are not actually real threads
-called "threads" that perl offers are nothing more than the (bad) process
+but only the windows process emulation ported to unix), Coro provides a
-emulation coming from the Windows platform: On standard operating systems
+full shared address space, which makes communication between coroutines
-they serve no purpose whatsoever, except by making your programs slow and
+very easy. And coroutines are fast, too: disabling the Windows process
-making them use a lot of memory. Best disable them when building perl, or
+emulation code in your perl and using Coro can easily result in a two to
-aks your software vendor/distributor to do it for you).
+four times speed increase for your programs.
+Coro achieves that by supporting multiple running interpreters that share
+data, which is especially useful to code pseudo-parallel processes and
+for event-based programming, such as multiple HTTP-GET requests running
+concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro
+into an event-based environment.
-In this module, coroutines are defined as "callchain + lexical variables +
+In this module, a coroutines is defined as "callchain + lexical variables
-@_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own callchain,
++ @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own
-its own set of lexicals and its own set of perls most important global
+callchain, its own set of lexicals and its own set of perls most important
-variables (see L<Coro::State> for more configuration).
+global variables (see L<Coro::State> for more configuration and background
+info).
+See also the C<SEE ALSO> section at the end of this document - the Coro
+module family is quite large.
 =cut
 package Coro;
 our $idle;    # idle handler
 our $main;    # main coroutine
 our $current; # current coroutine
-our $VERSION = 5.0;
+our $VERSION = "5.0";
 our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
 our %EXPORT_TAGS = (
       prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
 );
 our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
+=head1 GLOBAL VARIABLES
 =over 4
 =item $Coro::main
 This variable stores the coroutine object that represents the main
 $idle = sub {
    require Carp;
    Carp::croak ("FATAL: deadlock detected");
 };
-sub _cancel {
-   my ($self) = @_;
-   # free coroutine data and mark as destructed
-   $self->_destroy
-      or return;
-   # call all destruction callbacks
-   $_->(@{$self->{_status}})
-      for @{ delete $self->{_on_destroy} || [] };
-}
 # this coroutine is necessary because a coroutine
 # cannot destroy itself.
-my @destroy;
+our @destroy;
-my $manager;
+our $manager;
 $manager = new Coro sub {
    while () {
-      (shift @destroy)->_cancel
+      Coro::_cancel shift @destroy
          while @destroy;
       &schedule;
    }
 };
 $manager->{desc} = "[coro manager]";
 $manager->prio (PRIO_MAX);
 =back
-=head2 SIMPLE COROUTINE CREATION
+=head1 SIMPLE COROUTINE CREATION
 =over 4
 =item async { ... } [@args...]
 Similar to C<async>, but uses a coroutine pool, so you should not call
 terminate or join on it (although you are allowed to), and you get a
 coroutine that might have executed other code already (which can be good
 or bad :).
-On the plus side, this function is faster than creating (and destroying)
+On the plus side, this function is about twice as fast as creating (and
-a completly new coroutine, so if you need a lot of generic coroutines in
+destroying) a completely new coroutine, so if you need a lot of generic
-quick successsion, use C<async_pool>, not C<async>.
+coroutines in quick successsion, use C<async_pool>, not C<async>.
 The code block is executed in an C<eval> context and a warning will be
 issued in case of an exception instead of terminating the program, as
 C<async> does. As the coroutine is being reused, stuff like C<on_destroy>
 will not work in the expected way, unless you call terminate or cancel,
 coros as required.
 If you are concerned about pooled coroutines growing a lot because a
 single C<async_pool> used a lot of stackspace you can e.g. C<async_pool
 { terminate }> once per second or so to slowly replenish the pool. In
-addition to that, when the stacks used by a handler grows larger than 16kb
+addition to that, when the stacks used by a handler grows larger than 32kb
 (adjustable via $Coro::POOL_RSS) it will also be destroyed.
 =cut
 our $POOL_SIZE = 8;
-our $POOL_RSS  = 16 * 1024;
+our $POOL_RSS  = 32 * 1024;
 our @async_pool;
 sub pool_handler {
-   my $cb;
    while () {
       eval {
-         while () {
+         &{&_pool_handler} while 1;
-            _pool_1 $cb;
-            &$cb;
-            _pool_2 $cb;
-            &schedule;
-         }
       };
-      if ($@) {
-         last if $@ eq "\3async_pool terminate\2\n";
-         warn $@;
+      warn $@ if $@;
-      }
    }
-}
-sub async_pool(&@) {
-   # this is also inlined into the unblock_scheduler
-   my $coro = (pop @async_pool) || new Coro \&pool_handler;
-   $coro->{_invoke} = [@_];
-   $coro->ready;
-   $coro
 }
 =back
-=head2 STATIC METHODS
+=head1 STATIC METHODS
-Static methods are actually functions that operate on the current coroutine.
+Static methods are actually functions that implicitly operate on the
+current coroutine.
 =over 4
 =item schedule
 >> on that once some event happens, and last you call C<schedule> to put
 yourself to sleep. Note that a lot of things can wake your coroutine up,
 so you need to check whether the event indeed happened, e.g. by storing the
 status in a variable.
-The canonical way to wait on external events is this:
+See B<HOW TO WAIT FOR A CALLBACK>, below, for some ways to wait for callbacks.
-   {
-      # remember current coroutine
-      my $current = $Coro::current;
-      # register a hypothetical event handler
-      on_event_invoke sub {
-         # wake up sleeping coroutine
-         $current->ready;
-         undef $current;
-      };
-      # call schedule until event occurred.
-      # in case we are woken up for other reasons
-      # (current still defined), loop.
-      Coro::schedule while $current;
-   }
 =item cede
 "Cede" to other coroutines. This function puts the current coroutine into
 the ready queue and calls C<schedule>, which has the effect of giving
 you cannot free all of them, so if a coroutine that is not the main
 program calls this function, there will be some one-time resource leak.
 =cut
-sub terminate {
-   $current->cancel (@_);
-}
 sub killall {
    for (Coro::State::list) {
       $_->cancel
          if $_ != $current && UNIVERSAL::isa $_, "Coro";
    }
 }
 =back
-=head2 COROUTINE METHODS
+=head1 COROUTINE OBJECT METHODS
 These are the methods you can call on coroutine objects (or to create
 them).
 =over 4
 See C<async> and C<Coro::State::new> for additional info about the
 coroutine environment.
 =cut
-sub _run_coro {
+sub _terminate {
    terminate &{+shift};
-}
-sub new {
-   my $class = shift;
-   $class->SUPER::new (\&_run_coro, @_)
 }
 =item $success = $coroutine->ready
 Put the given coroutine into the end of its ready queue (there is one
 =cut
 sub cancel {
    my $self = shift;
-   $self->{_status} = [@_];
    if ($current == $self) {
-      push @destroy, $self;
+      terminate @_;
-      $manager->ready;
-      &schedule while 1;
    } else {
+      $self->{_status} = [@_];
       $self->_cancel;
    }
 }
+=item $coroutine->schedule_to
+Puts the current coroutine to sleep (like C<Coro::schedule>), but instead
+of continuing with the next coro from the ready queue, always switch to
+the given coroutine object (regardless of priority etc.). The readyness
+state of that coroutine isn't changed.
+This is an advanced method for special cases - I'd love to hear about any
+uses for this one.
+=item $coroutine->cede_to
+Like C<schedule_to>, but puts the current coroutine into the ready
+queue. This has the effect of temporarily switching to the given
+coroutine, and continuing some time later.
+This is an advanced method for special cases - I'd love to hear about any
+uses for this one.
 =item $coroutine->throw ([$scalar])
 If C<$throw> is specified and defined, it will be thrown as an exception
-inside the coroutine at the next convenient point in time (usually after
+inside the coroutine at the next convenient point in time. Otherwise
-it gains control at the next schedule/transfer/cede). Otherwise clears the
-exception object.
+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
+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>).
    my $old = $_[0]{desc};
    $_[0]{desc} = $_[1] if @_ > 1;
    $old;
 }
+sub transfer {
+   require Carp;
+   Carp::croak ("You must not call ->transfer on Coro objects. Use Coro::State objects or the ->schedule_to method. Caught");
+}
 =back
-=head2 GLOBAL FUNCTIONS
+=head1 GLOBAL FUNCTIONS
 =over 4
 =item Coro::nready
 # return immediately and can be reused) and because we cannot cede
 # inside an event callback.
 our $unblock_scheduler = new Coro sub {
    while () {
       while (my $cb = pop @unblock_queue) {
-         # this is an inlined copy of async_pool
+         &async_pool (@$cb);
-         my $coro = (pop @async_pool) || new Coro \&pool_handler;
-         $coro->{_invoke} = $cb;
-         $coro->ready;
-         cede; # for short-lived callbacks, this reduces pressure on the coro pool
+         # for short-lived callbacks, this reduces pressure on the coro pool
+         # as the chance is very high that the async_poll coro will be back
+         # in the idle state when cede returns
+         cede;
       }
       schedule; # sleep well
    }
 };
 $unblock_scheduler->{desc} = "[unblock_sub scheduler]";
       unshift @unblock_queue, [$cb, @_];
       $unblock_scheduler->ready;
    }
 }
+=item $cb = Coro::rouse_cb
+Create and return a "rouse callback". That's a code reference that, when
+called, will save its arguments and notify the owner coroutine of the
+callback.
+See the next function.
+=item @args = Coro::rouse_wait [$cb]
+Wait for the specified rouse callback (or the last one tht was created in
+this coroutine).
+As soon as the callback is invoked (or when the calback was invoked before
+C<rouse_wait>), it will return a copy of the arguments originally passed
+to the rouse callback.
+See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
 =back
 =cut
 1;
+=head1 HOW TO WAIT FOR A CALLBACK
+It is very common for a coroutine to wait for some callback to be
+called. This occurs naturally when you use coroutines 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 coroutine, 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:
+   my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... });
+But from withina coroutine, 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>.
+The first function, C<rouse_cb>, generates and returns a callback that,
+when invoked, will save it's arguments and notify the coroutine that
+created the callback.
+The second function, C<rouse_wait>, waits for the callback to be called
+(by calling C<schedule> to go to sleep) and returns the arguments
+originally passed to the callback.
+Using these functions, it becomes easy to write the C<wait_for_child>
+function mentioned above:
+   sub wait_for_child($) {
+      my ($pid) = @_;
+      my $watcher = AnyEvent->child (pid => $pid, cb => Coro::rouse_cb);
+      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>:
+   sub wait_for_child($) {
+      my ($pid) = @_;
+      # store the current coroutine in $current,
+      # and provide result variables for the closure passed to ->child
+      my $current = $Coro::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
+      });
+      # wait until the closure has been called
+      schedule while !$done;
+      $rstatus
+   }
 =head1 BUGS/LIMITATIONS
 =over 4
 =item coroutine switching not signal safe
 You must not switch to another coroutine from within a signal handler
 (only relevant with %SIG - most event libraries provide safe signals).
-That means you I<MUST NOT> call any fucntion that might "block" the
+That means you I<MUST NOT> call any function that might "block" the
 current coroutine - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
 anything that calls those. Everything else, including calling C<ready>,
 works.
 =back
 Debugging: L<Coro::Debug>.
 Support/Utility: L<Coro::Specific>, L<Coro::Util>.
-Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, L<Coro::SemaphoreSet>, L<Coro::RWLock>.
+Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>,
+L<Coro::SemaphoreSet>, L<Coro::RWLock>.
 IO/Timers: L<Coro::Timer>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::AIO>.
-Compatibility: L<Coro::LWP>, L<Coro::BDB>, L<Coro::Storable>, L<Coro::Select>.
+Compatibility: L<Coro::LWP> (but see also L<AnyEvent::HTTP> for
+a better-working alternative), L<Coro::BDB>, L<Coro::Storable>,
+L<Coro::Select>.
 XS API: L<Coro::MakeMaker>.
 Low level Configuration, Coroutine Environment: L<Coro::State>.

Diff Legend

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

Comparing cvsroot/Coro/Coro.pm (file contents): Revision 1.220 by root, Sun Nov 16 11:12:57 2008 UTC vs. Revision 1.237 by root, Sat Nov 22 16:37:11 2008 UTC

Diff Legend

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.220 by root, Sun Nov 16 11:12:57 2008 UTC vs.
Revision 1.237 by root, Sat Nov 22 16:37:11 2008 UTC