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

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.248 by root, Mon Dec 15 15:03:31 2008 UTC vs.
Revision 1.264 by root, Thu Aug 13 02:35:41 2009 UTC

 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.
 Unlike the so-called "Perl threads" (which are not actually real threads
-but only the windows process emulation ported to unix), Coro provides a
+but only the windows process emulation ported to unix, and as such act
-full shared address space, which makes communication between threads
+as processes), Coro provides a full shared address space, which makes
-very easy. And threads are fast, too: disabling the Windows process
+communication between threads very easy. And Coro's threads are fast,
-emulation code in your perl and using Coro can easily result in a two to
+too: disabling the Windows process emulation code in your perl and using
-four times speed increase for your programs.
+Coro can easily result in a two to four times speed increase for your
+programs. A parallel matrix multiplication benchmark runs over 300 times
+faster on a single core than perl's pseudo-threads on a quad core using
+all four cores.
 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 thread is defined as "callchain + lexical variables +
-@_ + $_ + $@ + $/ + C stack), that is, a thread has its own callchain,
+some package variables + 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 and background info).
 See also the C<SEE ALSO> section at the end of this document - the Coro
 module family is quite large.
 our $idle;    # idle handler
 our $main;    # main coro
 our $current; # current coro
-our $VERSION = 5.13;
+our $VERSION = 5.162;
 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.248 by root, Mon Dec 15 15:03:31 2008 UTC vs. Revision 1.264 by root, Thu Aug 13 02:35:41 2009 UTC

Diff Legend

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.248 by root, Mon Dec 15 15:03:31 2008 UTC vs.
Revision 1.264 by root, Thu Aug 13 02:35:41 2009 UTC