doco delay

doco delay

[Kevin Ryde]

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

Getting delay described, for completeness.

        * scheme-evaluation.texi (Delayed Evaluation): Add delay, reword
        promise? and force a bit, describe recursive forcing of a promise by
        its own code.

I'm assuming the R5RS sample code for promises is to be read as a
specification for what should happen in a recursive force.  It's the
way guile works at least.


Delayed Evaluation
==================

Promises are a convenient way to defer a calculation until its result
is actually needed, and to run such a calculation only once.

 - syntax: delay expr
     Return a promise object which holds the given EXPR expression,
     ready to be evaluated by a later `force'.

 - Scheme Procedure: promise? obj
 - C Function: scm_promise_p (obj)
     Return true if OBJ is a promise.

 - Scheme Procedure: force p
 - C Function: scm_force (prom)
     Return the value obtained from evaluating the EXPR in the given
     promise P.  If P has previously been forced then its EXPR is not
     evaluated again, instead the value obtained at that time is simply
     returned.

     During a `force', an EXPR can call `force' on its own promise,
     resulting in a further recursive evaluation of that EXPR.  The
     first evaluation to return gives the value for the promise.
     Higher evaluations run to completion in the normal way, but their
     results are ignored, `force' always returns the first value.



[-- Attachment #2: scheme-evaluation.texi.delay.diff --]
[-- Type: text/plain, Size: 1739 bytes --]

--- scheme-evaluation.texi.~1.9.~	2002-09-25 10:06:38.000000000 +1000
+++ scheme-evaluation.texi	2003-06-03 09:58:31.000000000 +1000
@@ -319,20 +319,36 @@
 
 @node Delayed Evaluation
 @section Delayed Evaluation
+@cindex delayed evaluation
+@cindex promises
 
-[delay]
+Promises are a convenient way to defer a calculation until its result
+is actually needed, and to run such a calculation only once.
+
+@deffn syntax delay expr
+@rnindex delay
+Return a promise object which holds the given @var{expr} expression,
+ready to be evaluated by a later @code{force}.
+@end deffn
 
 @deffn {Scheme Procedure} promise? obj
 @deffnx {C Function} scm_promise_p (obj)
-Return true if @var{obj} is a promise, i.e. a delayed computation
-(@pxref{Delayed evaluation,,,r5rs.info,The Revised^5 Report on Scheme}).
+Return true if @var{obj} is a promise.
 @end deffn
 
 @rnindex force
-@deffn {Scheme Procedure} force x
-@deffnx {C Function} scm_force (x)
-If the promise @var{x} has not been computed yet, compute and
-return @var{x}, otherwise just return the previously computed
+@deffn {Scheme Procedure} force p
+@deffnx {C Function} scm_force (prom)
+Return the value obtained from evaluating the @var{expr} in the given
+promise @var{p}.  If @var{p} has previously been forced then its
+@var{expr} is not evaluated again, instead the value obtained at that
+time is simply returned.
+
+During a @code{force}, an @var{expr} can call @code{force} on its own
+promise, resulting in a further recursive evaluation of that
+@var{expr}.  The first evaluation to return gives the value for the
+promise.  Higher evaluations run to completion in the normal way, but
+their results are ignored, @code{force} always returns the first
 value.
 @end deffn
 

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

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

Re: doco delay

[Kevin Ryde]

I wrote:
>
>         * scheme-evaluation.texi (Delayed Evaluation): Add delay, reword
>         promise? and force a bit, describe recursive forcing of a promise by
>         its own code.

In absense of violent objections I applied this change.


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