doco futures

[Kevin Ryde <user42@zip.com.au>]

[-- Attachment #1: Type: text/plain, Size: 888 bytes --]

A small start at getting some stuff out of the NEWS file and into the
manual.

	* scheme-scheduling.texi (Futures): New section.

Dunno if make-future or the C functions should appear too.  I'll leave
that to an executive decision.


Futures
=======

Futures are a convenient way to run a calculation in a new thread, and
only wait for the result when it's actually needed.

   Futures are similar to promises (*note Delayed Evaluation::), in that
they allow mainline code to continue immediately.  But `delay' doesn't
evaluate at all until forced, whereas `future' starts immediately in a
new thread.

 - syntax: future expr
     Begin evaluating EXPR in a new thread, and return a "future"
     object representing the calculation.

 - Scheme Procedure: future-ref f
     Return the value computed by the future F.  If F has not yet
     finished executing then wait for it to do so.



[-- Attachment #2: scheme-scheduling.texi.futures.diff --]
[-- Type: text/plain, Size: 1319 bytes --]

--- scheme-scheduling.texi.~1.10.~	2003-05-05 10:18:26.000000000 +1000
+++ scheme-scheduling.texi	2003-06-01 08:55:41.000000000 +1000
@@ -12,6 +12,7 @@
 * Dynamic Roots::               Root frames of execution.
 * Threads::                     Multiple threads of execution.
 * Fluids::                      Thread-local variables.
+* Futures::                     Delayed execution in new threads.
 @end menu
 
 
@@ -647,6 +648,30 @@
 when control enter or leaves the established dynamic extent.
 @end deffn
 
+
+@node Futures
+@section Futures
+@cindex futures
+
+Futures are a convenient way to run a calculation in a new thread, and
+only wait for the result when it's actually needed.
+
+Futures are similar to promises (@pxref{Delayed Evaluation}), in that
+they allow mainline code to continue immediately.  But @code{delay}
+doesn't evaluate at all until forced, whereas @code{future} starts
+immediately in a new thread.
+
+@deffn {syntax} future expr
+Begin evaluating @var{expr} in a new thread, and return a ``future''
+object representing the calculation.
+@end deffn
+
+@deffn {Scheme Procedure} future-ref f
+Return the value computed by the future @var{f}.  If @var{f} has not
+yet finished executing then wait for it to do so.
+@end deffn
+
+
 @c Local Variables:
 @c TeX-master: "guile.texi"
 @c End:

[-- Attachment #3: NEWS.futures.diff --]
[-- Type: text/plain, Size: 1213 bytes --]

--- NEWS.~1.393.~	2003-05-22 11:39:29.000000000 +1000
+++ NEWS	2003-05-31 15:12:07.000000000 +1000
@@ -278,27 +278,10 @@
 version string without the final micro-version number.  See "Changes
 to the distribution" above.
 
-** Futures
+** Futures: future, future-ref
 
-Futures is a way of providing an alternative evaluation policy, very
-similar in principle to "promises".  Like promises, futures allow the
-main process to continue instantly, but while promises postpone
-evaluation ("lazy" evaluation) until the value is requested, futures
-immediately starts evaluation in a parallel thread.
-
-Futures are good when you want to express that "I'll need the value of
-this computation sometime soon" and want to allow processing to go on
-in the background until that time arrives.
-
-** New syntax: future FORM
-
-Begin evaluation of FORM in a parallel thread and return the future
-immediately.  (Akin to 'delay'.)
-
-** New procedure: future-ref FUTURE
-
-Return the computed value of the future.  Wait if the computation is
-not finished.  (Akin to 'force'.)
+Futures are like promises, but begun immediately in a new thread.  See
+"Futures" in the reference manual.
 
 ** New syntax: parallel FORM ...
 

[-- Attachment #4: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel