[ViewVC] Diff of: cvs/Coro/README

Comparing Coro/README (file contents):
Revision 1.21 by root, Mon Dec 15 20:52:04 2008 UTC vs.
Revision 1.24 by root, Tue Jun 23 23:40:06 2009 UTC

 NAME
     Coro - the only real threads in perl
 SYNOPSIS
       use Coro;
-  async {
+      async {
          # some asynchronous thread of execution
          print "2\n";
          cede; # yield back to main
          print "4\n";
       };
       print "1\n";
       cede; # yield to coro
       print "3\n";
       cede; # and again
-  # use locking
+      # use locking
       use Coro::Semaphore;
       my $lock = new Coro::Semaphore;
       my $locked;
-  $lock->down;
+      $lock->down;
       $locked = 1;
       $lock->up;
 DESCRIPTION
     For a tutorial-style introduction, please read the Coro::Intro manpage.
         These functions implement the same concept as "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 them
+        They slow down thread switching considerably for coros that use them
+        (about 40% for a BLOCK with a single assignment, so thread switching
-        (But coro switching is still reasonably fast if the handlers are
+        is still reasonably fast if the handlers are fast).
-        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 "tzset", but by
         using "on_enter" and "on_leave", which remember/change the current
         timezone and restore the previous value, respectively, the timezone
-        is only changes for the coro that installed those handlers.
+        is only changed for the coro that installed those handlers.
            use POSIX qw(tzset);
            async {
               my $old_tz; # store outside TZ value here
            };
         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 () { }
+           };
     killall
         Kills/terminates/cancels all coros except the currently running one.
         Note that while this will try to free some of the main interpreter
         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.
+    $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.
+    $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.
     $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.

Diff Legend

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

Comparing Coro/README (file contents): Revision 1.21 by root, Mon Dec 15 20:52:04 2008 UTC vs. Revision 1.24 by root, Tue Jun 23 23:40:06 2009 UTC

Diff Legend

Comparing Coro/README (file contents):
Revision 1.21 by root, Mon Dec 15 20:52:04 2008 UTC vs.
Revision 1.24 by root, Tue Jun 23 23:40:06 2009 UTC