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

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.232 by root, Fri Nov 21 02:39:40 2008 UTC vs.
Revision 1.247 by root, Mon Dec 15 02:07:11 2008 UTC

 =head1 NAME
-Coro - coroutine process abstraction
+Coro - the only 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 continuations in general, most often
-multiple running interpreters that share data, which is especially useful
+in the form of cooperative threads (also called coroutines in the
-to code pseudo-parallel processes and for event-based programming, such as
+documentation). They are similar to kernel threads but don't (in general)
-multiple HTTP-GET requests running concurrently. See L<Coro::AnyEvent> to
+run in parallel at the same time even on SMP machines. The specific flavor
-learn more.
+of thread offered by this module also guarantees you that it will not
+switch between threads unless necessary, at easily-identified points in
+your program, so locking and parallel access are rarely an issue, making
+thread 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 threads
-they serve no purpose whatsoever, except by making your programs slow and
+very easy. And threads 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 thread is defined as "callchain + lexical variables +
-@_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own callchain,
+@_ + $_ + $@ + $/ + C stack), that is, a thread has its own callchain,
 its own set of lexicals and its own set of perls most important global
-variables (see L<Coro::State> for more configuration).
+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;
 use strict qw(vars subs);
 no warnings "uninitialized";
+use Guard ();
 use Coro::State;
 use base qw(Coro::State Exporter);
 our $idle;    # idle handler
 our $main;    # main coroutine
 our $current; # current coroutine
-our $VERSION = "5.0";
+our $VERSION = 5.13;
 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
 sub current() { $current } # [DEPRECATED]
 =item $Coro::idle
 This variable is mainly useful to integrate Coro into event loops. It is
-usually better to rely on L<Coro::AnyEvent> or LC<Coro::EV>, as this is
+usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is
 pretty low-level functionality.
-This variable stores a callback that is called whenever the scheduler
+This variable stores either a coroutine or a callback.
+If it is a callback, the it is called whenever the scheduler finds no
-finds no ready coroutines to run. The default implementation prints
+ready coroutines to run. The default implementation prints "FATAL:
-"FATAL: deadlock detected" and exits, because the program has no other way
+deadlock detected" and exits, because the program has no other way to
-to continue.
+continue.
+If it is a coroutine object, then this object will be readied (without
+invoking any ready hooks, however) when the scheduler finds no other ready
+coroutines to run.
-This hook is overwritten by modules such as C<Coro::Timer> and
+This hook is overwritten by modules such as C<Coro::EV> and
 C<Coro::AnyEvent> to wait on an external event that hopefully wake up a
 coroutine so the scheduler can run it.
 Note that the callback I<must not>, under any circumstances, block
 the current coroutine. Normally, this is achieved by having an "idle
 coroutine" that calls the event loop and then blocks again, and then
-readying that coroutine in the idle handler.
+readying that coroutine in the idle handler, or by simply placing the idle
+coroutine in this variable.
 See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this
 technique.
 Please note that if your callback recursively invokes perl (e.g. for event
 $manager->{desc} = "[coro manager]";
 $manager->prio (PRIO_MAX);
 =back
-=head2 SIMPLE COROUTINE CREATION
+=head1 SIMPLE COROUTINE CREATION
 =over 4
 =item async { ... } [@args...]
-Create a new coroutine and return it's coroutine object (usually
+Create a new coroutine and return its coroutine object (usually
 unused). The coroutine will be put into the ready queue, so
 it will start running automatically on the next scheduler run.
 The first argument is a codeblock/closure that should be executed in the
 coroutine. When it returns argument returns the coroutine is automatically
    }
 }
 =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
 =item terminate [arg...]
 Terminates the current coroutine with the given status values (see L<cancel>).
+=item Coro::on_enter BLOCK, Coro::on_leave BLOCK
+These function install enter and leave winders in the current scope. The
+enter block will be executed when on_enter is called and whenever the
+current coroutine is re-entered by the scheduler, while the leave block is
+executed whenever the current coroutine is blocked by the scheduler, and
+also when the containing scope is exited (by whatever means, be it exit,
+die, last etc.).
+I<Neither invoking the scheduler, nor exceptions, are allowed within those
+BLOCKs>. That means: do not even think about calling C<die> without an
+eval, and do not even think of entering the scheduler in any way.
+Since both BLOCKs are tied to the current scope, they will automatically
+be removed when the current scope exits.
+These functions implement the same concept as C<dynamic-wind> in scheme
+does, and are useful when you want to localise some resource to a specific
+coroutine.
+They slow down coroutine switching considerably for coroutines that use
+them (But coroutine switching is still reasonably fast if the handlers are
+fast).
+These functions are best understood by an example: The following function
+will change the current timezone to "Antarctica/South_Pole", which
+requires a call to C<tzset>, but by using C<on_enter> and C<on_leave>,
+which remember/change the current timezone and restore the previous
+value, respectively, the timezone is only changes for the coroutine that
+installed those handlers.
+   use POSIX qw(tzset);
+   async {
+      my $old_tz; # store outside TZ value here
+      Coro::on_enter {
+         $old_tz = $ENV{TZ}; # remember the old value
+         $ENV{TZ} = "Antarctica/South_Pole";
+         tzset; # enable new value
+      };
+      Coro::on_leave {
+         $ENV{TZ} = $old_tz;
+         tzset; # restore old value
+      };
+      # at this place, the timezone is Antarctica/South_Pole,
+      # without disturbing the TZ of any other coroutine.
+   };
+This can be used to localise about any resource (locale, uid, current
+working directory etc.) to a block, despite the existance of other
+coroutines.
 =item killall
-Kills/terminates/cancels all coroutines except the currently running
+Kills/terminates/cancels all coroutines except the currently running one.
-one. This is useful after a fork, either in the child or the parent, as
-usually only one of them should inherit the running coroutines.
-Note that while this will try to free some of the main programs resources,
+Note that while this will try to free some of the main interpreter
+resources if the calling coroutine isn't the main coroutine, but one
-you cannot free all of them, so if a coroutine that is not the main
+cannot free all of them, so if a coroutine that is not the main coroutine
-program calls this function, there will be some one-time resource leak.
+calls this function, there will be some one-time resource leak.
 =cut
 sub killall {
    for (Coro::State::list) {
    }
 }
 =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 _terminate {
+sub _coro_run {
    terminate &{+shift};
 }
 =item $success = $coroutine->ready
    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
 would cause a deadlock unless there is an idle handler that wakes up some
 coroutines.
 =item my $guard = Coro::guard { ... }
-This creates and returns a guard object. Nothing happens until the object
+This function still exists, but is deprecated. Please use the
-gets destroyed, in which case the codeblock given as argument will be
+C<Guard::guard> function instead.
-executed. This is useful to free locks or other resources in case of a
-runtime error or when the coroutine gets canceled, as in both cases the
-guard block will be executed. The guard object supports only one method,
-C<< ->cancel >>, which will keep the codeblock from being executed.
-Example: set some flag and clear it again when the coroutine gets canceled
-or the function returns:
-   sub do_something {
-      my $guard = Coro::guard { $busy = 0 };
-      $busy = 1;
-      # do something that requires $busy to be true
-   }
 =cut
-sub guard(&) {
+BEGIN { *guard = \&Guard::guard }
-   bless \(my $cb = $_[0]), "Coro::guard"
-}
-sub Coro::guard::cancel {
-   ${$_[0]} = sub { };
-}
-sub Coro::guard::DESTROY {
-   ${$_[0]}->();
-}
 =item unblock_sub { ... }
 This utility function takes a BLOCK or code reference and "unblocks" it,
 returning a new coderef. Unblocking means that calling the new coderef
 original code ref will be called (with parameters) from within another
 coroutine.
 The reason this function exists is that many event libraries (such as the
 venerable L<Event|Event> module) are not coroutine-safe (a weaker form
-of thread-safety). This means you must not block within event callbacks,
+of reentrancy). This means you must not block within event callbacks,
 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>.
 This function allows your callbacks to block by executing them in another
 coroutine where it is safe to block. One example where blocking is handy
    }
 }
 =item $cb = Coro::rouse_cb
-Create and return a "rouse callback". That's a code reference that, when
+Create and return a "rouse callback". That's a code reference that,
-called, will save its arguments and notify the owner coroutine of the
+when called, will remember a copy of its arguments and notify the owner
-callback.
+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
+Wait for the specified rouse callback (or the last one that was created in
 this coroutine).
-As soon as the callback is invoked (or when the calback was invoked before
+As soon as the callback is invoked (or when the callback was invoked
-C<rouse_wait>), it will return a copy of the arguments originally passed
+before C<rouse_wait>), it will return the arguments originally passed to
-to the rouse callback.
+the rouse callback.
 See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
 =back
 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
+when invoked, will save its 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.
 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
+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.
 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 and 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>.
+I/O and 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 with other modules: 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>.
+Low level Configuration, Thread Environment, Continuations: L<Coro::State>.
 =head1 AUTHOR
  Marc Lehmann <schmorp@schmorp.de>
  http://home.schmorp.de/

Diff Legend

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

Comparing cvsroot/Coro/Coro.pm (file contents): Revision 1.232 by root, Fri Nov 21 02:39:40 2008 UTC vs. Revision 1.247 by root, Mon Dec 15 02:07:11 2008 UTC

Diff Legend

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.232 by root, Fri Nov 21 02:39:40 2008 UTC vs.
Revision 1.247 by root, Mon Dec 15 02:07:11 2008 UTC