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

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.249 by root, Mon Dec 15 15:21:25 2008 UTC vs.
Revision 1.265 by root, Sat Aug 22 22:36:23 2009 UTC

 our $idle;    # idle handler
 our $main;    # main coro
 our $current; # current coro
-our $VERSION = 5.13;
+our $VERSION = 5.17;
 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)],
 );
 Example: Create a new coro that just prints its arguments.
    async {
       print "@_\n";
    } 1,2,3,4;
-=cut
-sub async(&@) {
-   my $coro = new Coro @_;
-   $coro->ready;
-   $coro
-}
 =item async_pool { ... } [@args...]
 Similar to C<async>, but uses a coro pool, so you should not call
 terminate or join on it (although you are allowed to), and you get a
 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
 coro.
-They slow down coro switching considerably for coros that use
+They slow down thread switching considerably for coros that use them
-them (But coro switching is still reasonably fast if the handlers are
+(about 40% for a BLOCK with a single assignment, so thread switching is
-fast).
+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 coro that
+value, respectively, the timezone is only changed for the coro that
 installed those handlers.
    use POSIX qw(tzset);
    async {
    };
 This can be used to localise about any resource (locale, uid, current
 working directory etc.) to a block, despite the existance of other
 coros.
+Another interesting example implements time-sliced multitasking using
+interval timers (this could obviously be optimised, but does the job):
+   # "timeslice" the given block
+   sub timeslice(&) {
+      use Time::HiRes ();
+      Coro::on_enter {
+         # on entering the thread, we set an VTALRM handler to cede
+         $SIG{VTALRM} = sub { cede };
+         # and then start the interval timer
+         Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01;
+      };
+      Coro::on_leave {
+         # on leaving the thread, we stop the interval timer again
+         Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0;
+      };
+      &{+shift};
+   }
+   # use like this:
+   timeslice {
+      # The following is an endless loop that would normally
+      # monopolise the process. Since it runs in a timesliced
+      # environment, it will regularly cede to other threads.
+      while () { }
+   };
 =item killall
 Kills/terminates/cancels all coros except the currently running one.
 the ready queue, do nothing and return false.
 This ensures that the scheduler will resume this coro automatically
 once all the coro of higher priority and all coro of the same
 priority that were put into the ready queue earlier have been resumed.
+=item $coro->suspend
+Suspends the specified coro. A suspended coro works just like any other
+coro, except that the scheduler will not select a suspended coro for
+execution.
+Suspending a coro can be useful when you want to keep the coro from
+running, but you don't want to destroy it, or when you want to temporarily
+freeze a coro (e.g. for debugging) to resume it later.
+A scenario for the former would be to suspend all (other) coros after a
+fork and keep them alive, so their destructors aren't called, but new
+coros can be created.
+=item $coro->resume
+If the specified coro was suspended, it will be resumed. Note that when
+the coro was in the ready queue when it was suspended, it might have been
+unreadied by the scheduler, so an activation might have been lost.
+To avoid this, it is best to put a suspended coro into the ready queue
+unconditionally, as every synchronisation mechanism must protect itself
+against spurious wakeups, and the one in the Coro family certainly do
+that.
 =item $is_ready = $coro->is_ready
 Returns true iff the Coro object is in the ready queue. Unless the Coro
 object gets destroyed, it will eventually be scheduled by the scheduler.
 Wait for the specified rouse callback (or the last one that was created in
 this coro).
 As soon as the callback is invoked (or when the callback was invoked
 before C<rouse_wait>), it will return the arguments originally passed to
-the rouse callback.
+the rouse callback. In scalar context, that means you get the I<last>
+argument, just as if C<rouse_wait> had a C<return ($a1, $a2, $a3...)>
+statement at the end.
 See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
 =back

Diff Legend

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

Comparing cvsroot/Coro/Coro.pm (file contents): Revision 1.249 by root, Mon Dec 15 15:21:25 2008 UTC vs. Revision 1.265 by root, Sat Aug 22 22:36:23 2009 UTC

Diff Legend

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.249 by root, Mon Dec 15 15:21:25 2008 UTC vs.
Revision 1.265 by root, Sat Aug 22 22:36:23 2009 UTC