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

Comparing Coro/Coro.pm (file contents):
Revision 1.211 by root, Mon Nov 10 00:02:29 2008 UTC vs.
Revision 1.225 by root, Wed Nov 19 15:29:57 2008 UTC

 our $idle;    # idle handler
 our $main;    # main coroutine
 our $current; # current coroutine
-our $VERSION = 4.9;
+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)],
 );
 coroutines, it is mainly useful to compare again C<$Coro::current>, to see
 whether you are running in the main program or not.
 =cut
-$main = new Coro;
+# $main is now being initialised by Coro::State
 =item $Coro::current
 The coroutine object representing the current coroutine (the last
 coroutine that the Coro scheduler switched to). The initial value is
-C<$main> (of course).
+C<$Coro::main> (of course).
 This variable is B<strictly> I<read-only>. You can take copies of the
 value stored in it and use it as any other coroutine object, but you must
 not otherwise modify the variable itself.
 =cut
-$main->{desc} = "[main::]";
-# maybe some other module used Coro::Specific before...
-$main->{_specific} = $current->{_specific}
-   if $current;
-_set_current $main;
 sub current() { $current } # [DEPRECATED]
 =item $Coro::idle
       }
    }
 }
 sub async_pool(&@) {
-   # this is also inlined into the unlock_scheduler
+   # this is also inlined into the unblock_scheduler
    my $coro = (pop @async_pool) || new Coro \&pool_handler;
    $coro->{_invoke} = [@_];
    $coro->ready;
 >> 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
 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
 }
 =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>).
       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 fork with pthread backend
+When Coro is compiled using the pthread backend (which isn't recommended
+but required on many BSDs as their libcs are completely broken), then
+coroutines will not survive a fork. There is no known workaround except to
+fix your libc and use a saner backend.
+=item perl process emulation ("threads")
 This module is not perl-pseudo-thread-safe. You should only ever use this
 module from the same 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 this
+this). I recommend disabling thread support and using processes, as having
-is much faster and uses less memory.
+the windows process emulation enabled under unix roughly halves perl
+performance, even when not used.
+=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 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
 =head1 SEE ALSO
 Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.

Diff Legend

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

Comparing Coro/Coro.pm (file contents): Revision 1.211 by root, Mon Nov 10 00:02:29 2008 UTC vs. Revision 1.225 by root, Wed Nov 19 15:29:57 2008 UTC

Diff Legend

Comparing Coro/Coro.pm (file contents):
Revision 1.211 by root, Mon Nov 10 00:02:29 2008 UTC vs.
Revision 1.225 by root, Wed Nov 19 15:29:57 2008 UTC