doco delay

[Kevin Ryde]

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.

scheme-evaluation.texi.delay.diff
Description: Text document