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

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.237 by root, Sat Nov 22 16:37:11 2008 UTC vs.
Revision 1.247 by root, Mon Dec 15 02:07:11 2008 UTC

 =head1 NAME
-Coro - real threads in perl
+Coro - the only real threads in perl
 =head1 SYNOPSIS
   use Coro;
 =head1 DESCRIPTION
 For a tutorial-style introduction, please read the L<Coro::Intro>
 manpage. This manpage mainly contains reference information.
-This module collection manages coroutines, that is, cooperative
+This module collection manages continuations in general, most often
-threads. Coroutines are similar to kernel threads but don't (in general)
+in the form of cooperative threads (also called coroutines in the
+documentation). They are similar to kernel threads but don't (in general)
 run in parallel at the same time even on SMP machines. The specific flavor
-of coroutine used in this module also guarantees you that it will not
+of thread offered by this module also guarantees you that it will not
-switch between coroutines unless necessary, at easily-identified points
+switch between threads unless necessary, at easily-identified points in
-in your program, so locking and parallel access are rarely an issue,
+your program, so locking and parallel access are rarely an issue, making
-making coroutine programming much safer and easier than using other thread
+thread programming much safer and easier than using other thread models.
-models.
 Unlike the so-called "Perl threads" (which are not actually real threads
 but only the windows process emulation ported to unix), Coro provides a
-full shared address space, which makes communication between coroutines
+full shared address space, which makes communication between threads
-very easy. And coroutines are fast, too: disabling the Windows process
+very easy. And threads are fast, too: disabling the Windows process
 emulation code in your perl and using Coro can easily result in a two to
 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, a coroutines is 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
+@_ + $_ + $@ + $/ + C stack), that is, a thread has its own callchain,
-callchain, its own set of lexicals and its own set of perls most important
+its own set of lexicals and its own set of perls most important global
-global variables (see L<Coro::State> for more configuration and background
+variables (see L<Coro::State> for more configuration and background info).
-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)],
 );
 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
 =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
 =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) {
 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
 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>,
+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> (but see also L<AnyEvent::HTTP> for
+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.237 by root, Sat Nov 22 16:37:11 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.237 by root, Sat Nov 22 16:37:11 2008 UTC vs.
Revision 1.247 by root, Mon Dec 15 02:07:11 2008 UTC