promises.texi (4368B)
1 @c -*-texinfo-*- 2 @setfilename ../src/promises 3 4 @node Promises, Keyed Variables, Encapsulations, Top 5 @comment node-name, next, previous, up 6 7 @chapter Promises 8 @cindex promises 9 10 @c TODO xref to $lazy, memoize, force 11 A promise is an object that represents the potential to determine a 12 value. The value may be the result of an arbitrary computation that 13 will not be performed until the value must be determined (constructor 14 @code{$lazy}); or, in advanced usage, the value may be determined 15 before the promise is constructed (constructor @code{memoize}). 16 17 The value determined by a promise is obtained by forcing it 18 (applicative @code{force}). A given promise cannot determine 19 different values on different occasions that it is forced. Also, if a 20 promise determines its value by computation, and that computation has 21 already been completed, forcing the promise again will produce the 22 previously determined result without re-initiating the computation to 23 determine it. 24 25 The Kernel data type promise is encapsulated. 26 27 @c TODO add xref to eq? and equal? 28 The general rules for predicate @code{eq?} only require it to 29 distinguish promises if they can exhibit different behavior; the 30 resulting leeway for variation between implementations is similar, in 31 both cause and effect, to that for @code{eq?}-ness of operatives. For 32 example, if two promises, constructed on different occasions, would 33 perform the same computation to determine their values, and that 34 computation has no side-effects and must always return the same value, 35 the promises may or may not be @code{eq?}. Two promises are 36 @code{equal?} iff they are @code{eq?}. 37 38 @deffn Applicative promise? (promise? . objects) 39 The primitive type predicate for type promise. @code{promise?} 40 returns true iff all the objects in @code{objects} are of type 41 promise. 42 @end deffn 43 44 @deffn Applicative force (force object) 45 If @code{object} is a promise, applicative @code{force} returns the 46 value determined by promise; otherwise, it returns @code{object}. 47 48 The means used to force a promise depend on how the promise was 49 constructed. The description of each promise constructor specifies 50 how to force promises constructed by that constructor. 51 @end deffn 52 53 @deffn Operative $lazy ($lazy expression) 54 Operative @code{$lazy} constructs and returns a new object of type 55 promise, representing potential evaluation of expression in the 56 dynamic environment from which @code{$lazy} was called. 57 58 When the promise is forced, if a value has not previously been 59 determined for it, @code{expression} is evaluated in the dynamic 60 environment of the constructing call to @code{$lazy}. If, when the 61 evaluation returns a result, a value is found to have been determined 62 for the promise during the evaluation, the result is discarded in 63 favor of the previously determined value; otherwise, the result is 64 forced, and the value returned by that forcing becomes the value 65 determined by the promise. 66 67 @c TODO add xref to tail context 68 Forcing an undetermined lazy promise (i.e., a promise constructed by 69 $lazy for which no value has yet been determined) may cause a 70 sequential series of evaluations, each of which returns a promise that 71 is forced and thus initiates the next evaluation in the series. The 72 implementation must support series of this kind with unbounded length 73 (i.e., unbounded number of sequential evaluations). 74 75 @c TODO add xref to eq? 76 Note that forcing concerns the value determined by a given promise, 77 not the result of evaluating a given expression in a given 78 environment. Distinct promises (judged by @code{eq?} represent 79 different occasions of evaluation; so, even if they do represent 80 evaluation of the same expression in the same environment, forcing one 81 does not necessarily determine the value for the other, and actual 82 evaluation will take place the first time each of them is forced. 83 @end deffn 84 85 @deffn Applicative memoize (memoize object) 86 Applicative @code{memoize} constructs and returns a new object of 87 type promise, representing memoization of @code{object}. Whenever the 88 promise is forced, it determines @code{object}. 89 @end deffn 90 91 @deffn Operative $delay ($delay <expression>) 92 Operative @code{delay} behaves as the composition of @code{$lazy} and 93 @code{memoize}, that is: 94 @example 95 ($delay <expr>) @equiv{} ($lazy (memoize <expr>)) 96 @end example 97 SOURCE NOTE: this is taken from r7rs. 98 @end deffn