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

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.239 by root, Mon Nov 24 07:55:28 2008 UTC vs.
Revision 1.247 by root, Mon Dec 15 02:07:11 2008 UTC

 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.1;
+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)],
 );
 =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
 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.

Diff Legend

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

Comparing cvsroot/Coro/Coro.pm (file contents): Revision 1.239 by root, Mon Nov 24 07:55:28 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.239 by root, Mon Nov 24 07:55:28 2008 UTC vs.
Revision 1.247 by root, Mon Dec 15 02:07:11 2008 UTC