summaryrefslogtreecommitdiff
path: root/doc/ref/srfi-modules.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref/srfi-modules.texi')
-rw-r--r--doc/ref/srfi-modules.texi57
1 files changed, 35 insertions, 22 deletions
diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi
index af1afc013..e60dbb4e1 100644
--- a/doc/ref/srfi-modules.texi
+++ b/doc/ref/srfi-modules.texi
@@ -3833,45 +3833,58 @@ words, no program that uses the R5RS definitions of delay and force will
break if those definition are replaced by the SRFI-45 definitions of
delay and force.
+Guile compatibly extends SRFI-45 to support multiple values. It also
+adds @code{promise?} to the list of exports.
+
+@deffn {Scheme Procedure} promise? obj
+Return true if @var{obj} is an SRFI-45 promise, otherwise return false.
+@end deffn
+
@deffn {Scheme Syntax} delay expression
-Takes an expression of arbitrary type @var{a} and returns a promise of
-type @code{(Promise @var{a})} which at some point in the future may be
-asked (by the @code{force} procedure) to evaluate the expression and
-deliver the resulting value.
+Takes an expression and returns a promise which at some point in the
+future may be asked (by the @code{force} procedure) to evaluate the
+expression and deliver the resulting value(s).
@end deffn
@deffn {Scheme Syntax} lazy expression
-Takes an expression of type @code{(Promise @var{a})} and returns a
-promise of type @code{(Promise @var{a})} which at some point in the
-future may be asked (by the @code{force} procedure) to evaluate the
-expression and deliver the resulting promise.
+Takes an expression (which must evaluate to a promise) and returns a
+promise which at some point in the future may be asked (by the
+@code{force} procedure) to evaluate the expression and deliver the
+resulting promise.
@end deffn
-@deffn {Scheme Procedure} force expression
-Takes an argument of type @code{(Promise @var{a})} and returns a value
-of type @var{a} as follows: If a value of type @var{a} has been computed
-for the promise, this value is returned. Otherwise, the promise is
-first evaluated, then overwritten by the obtained promise or value, and
-then force is again applied (iteratively) to the promise.
+@deffn {Scheme Procedure} force promise
+Takes a promise and returns the associated value(s) as follows: If
+value(s) have been computed for the promise, these value(s) are
+returned. Otherwise, the promise is first evaluated, then overwritten
+by the obtained promise or value(s), and then force is again applied
+(iteratively) to the promise.
@end deffn
-@deffn {Scheme Procedure} eager expression
-Takes an argument of type @var{a} and returns a value of type
-@code{(Promise @var{a})}. As opposed to @code{delay}, the argument is
-evaluated eagerly. Semantically, writing @code{(eager expression)} is
-equivalent to writing
+@deffn {Scheme Procedure} eager obj ...
+Takes any number of argument(s) and returns a promise. As opposed to
+@code{delay}, the argument(s) are evaluated eagerly. Semantically,
+writing @code{(eager expression)} is equivalent to writing
@lisp
(let ((value expression)) (delay value)).
@end lisp
However, the former is more efficient since it does not require
-unnecessary creation and evaluation of thunks. We also have the
-equivalence
+unnecessary creation and evaluation of thunks. For expressions that
+return a single value, we also have the equivalence
@lisp
(delay expression) = (lazy (eager expression))
@end lisp
+
+More generally, the following equivalence holds:
+
+@lisp
+(delay expression) = (lazy (call-with-values
+ (lambda () expression)
+ eager))
+@end lisp
@end deffn
The following reduction rules may be helpful for reasoning about these
@@ -3881,7 +3894,7 @@ usage semantics specified above:
@lisp
(force (delay expression)) -> expression
(force (lazy expression)) -> (force expression)
-(force (eager value)) -> value
+(force (eager obj ...)) -> (values obj ...)
@end lisp
@subsubheading Correct usage