source: project/wiki/eggref/5/continuations @ 37403

Last change on this file since 37403 was 37403, checked in by juergen, 20 months ago

continuations 1.0 docu

File size: 7.2 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== continuations
5
6This library contains two interfaces to continuations, Marc Feeley's and
7Matt Might's, both with some syntactic sugar.
8
9In Mark Feeley's interface, continuations are a datatype separate from
10procedures. Hence it provides a continuation? predicate. I've stripped
11the prefix from the procedures continuation-capture and
12continuation-graft and renamed continuation-return throw. This latter
13procedure is accompanied in this module by a macro named catch, so that
14the usual catch-throw-semantics of other languages is available.  But
15note, that in this pattern, the continuation is a Scheme object, and
16like every Scheme object it has indefinite extent, hence can be
17exported, saved in other data-structures etc. So this pattern is much
18more powerful than the corresponding pattern in other languages.
19
20Some other procedures are provided as well, in particular
21continuation->procedure, which does what the name says, and
22continuations, which provides offline documentation to the module. Like
23in my other modules, the call (continuations) lists the exported
24symbols, and (continuations sym) provides documentation of the exported
25symbol sym.
26
27And then there is the infamous goto, which albeit dangerous is
28sometimes useful, e.g. in backtracking ....
29 
30Matt Might's interface is proveded in two flavors, with continuations,
31checked by continuation?, and escape procedures, checked by
32escape-procedure?.  This makes possible code written in an idiom similar
33to the setjmp-longjmp-pair in C.
34
35=== The escape-procedure interface
36
37==== escape-procedure
38
39<procedure>(escape-procedure)</procedure>
40
41captures and returns the current continuation as an escape procedure.
42Typically used as follows
43
44<enscript highlight=scheme>
45(let ((cc (escape-procedure)))
46  (cond
47    ((escape-procedure? cc)
48     ;; normal body
49     ;; possibly calling (cc val) ...
50    ((ok? cc)
51     ;; exceptional case
52     ;; do something with cc ...))
53</enscript>
54
55Note, that the let is invoked twice, first after the call to
56escape-procedure, then with the object val, which was
57bound to cc by calling (cc val).
58
59==== escape-procedure?
60
61<procedure>(escape-procedure? xpr)</procedure>
62
63type predicate, defined simultaneously with escape-procedure
64
65
66=== The continuation interface
67
68==== continuation
69
70<procedure>(continuation)</procedure>
71
72captures and returns the current continuation. Typically used as follows
73
74<enscript highlight=scheme>
75(let ((cc (current)))
76  (if (continuation? cc)
77    ... (throw cc val) ...
78    ... do something with val ...))
79</enscript>
80
81Note, that the let is invoked twice, first after the call to
82current, then with the object val, which was thrown to cc.
83
84==== continuation?
85
86<procedure>(continuation? xpr)</procedure>
87
88type predicate
89
90==== continuation->procedure
91
92<procedure>(continuation->procedure cont)</procedure>
93
94transforms a continuation into a procedure
95
96==== capture
97
98<procedure>(capture proc)</procedure>
99
100The same as call/cc but with a different datatype:
101Captures the current continuation as a continuation datatype (contrary
102to a procedure datatype in call/cc) and calls proc with that
103continuation as its only argument.
104
105==== graft
106
107<procedure>(graft cont thunk)</procedure>
108
109tail-calls thunk with the implicit continuation cont.
110
111==== throw
112
113<procedure>(throw cont val ....)</procedure>
114
115throws the values val .... to the continuation cont.
116
117==== catch
118
119<macro>(catch cont xpr ....)</macro>
120
121The same as let/cc of miscmacros but with a different datatype:
122Binds the cont variable to the current continuation as a continuation
123and executes the body xpr .... in this context. Typically used as
124follows
125 
126<enscript highlight=scheme>
127(catch k
128  ...
129  (if ...
130    (throw k val)
131    ...))
132</enscript>
133
134==== goto
135
136<procedure>(goto cc)</procedure>
137
138The infamous goto, but with a continuation as argument instead of a label.
139
140==== call
141
142<procedure>(call receiver)</procedure>
143
144The same as call/cc, but implemented via capture.
145
146==== continuations
147
148<procedure>(continuations sym ..)</procedure>
149
150documentation procedure
151
152==== escape procedures
153
154</enscript>
155
156== Requirements
157
158none
159
160=== Examples
161
162<enscript highlight=scheme>
163(import continuations)
164
165(define 1+ #f)
166
167;; ... with catch
168(define (init)
169  (+ 1 (catch cont
170              (set! 1+ (continuation->procedure cont))
171              (throw cont 0))))
172
173;; ... with continuation
174(define (init-again)
175  (+ 1 (let ((cc (current-continuation)))
176         (cond
177           ((continuation? cc)
178            (set! 1+ (continuation->procedure cc))
179            (throw cc 0))
180           (else cc)))))
181
182(define (search ok? lst)
183  (catch return
184         (for-each (lambda (item)
185                     (if (ok? item)
186                       (throw return item)))
187                   lst)
188         #f))
189
190(define (search-with-goto ok? lst)
191  (let ((start (continuation)))
192    (cond
193      ((null? lst) #f)
194      ((ok? (car lst)) (car lst))
195      (else
196        (set! lst (cdr lst))
197        (goto start)))))
198
199;; nonlocal return: throw and catch in different procedures
200(define (treat ok?)
201  (lambda (item cont)
202    (if (ok? item)
203      (throw cont item))))
204
205(define (handled-search handle lst)
206  (catch return
207         (for-each (lambda (item)
208                     (handle item return))
209                   lst)
210         #f))
211
212(define (product . nums)
213  (let ((cc (escape-procedure)))
214    (cond
215      ((escape-procedure? cc) ; continuation cc just created
216       (print "NORMAL BODY")
217       (cond
218         ((null? nums) 1)
219         ((zero? (car nums))
220          (cc 0))
221         (else
222           (* (car nums) (apply product (cdr nums))))))
223      ((number? cc) ; cc has been thrown a number
224       (print "EXCEPTIONAL CASE")
225       cc)
226      )))
227
228</enscript>
229
230== Last update
231
232Mar 17, 2019
233
234== Author
235
236[[/users/juergen-lorenz|Juergen Lorenz]]
237
238== License
239
240 Copyright (c) 2013-2019, Juergen Lorenz
241 All rights reserved.
242
243 Redistribution and use in source and binary forms, with or without
244 modification, are permitted provided that the following conditions are
245 met:
246 
247 Redistributions of source code must retain the above copyright
248 notice, this list of conditions and the following disclaimer.
249 
250 Redistributions in binary form must reproduce the above copyright
251 notice, this list of conditions and the following disclaimer in the
252 documentation and/or other materials provided with the distribution.
253 Neither the name of the author nor the names of its contributors may be
254 used to endorse or promote products derived from this software without
255 specific prior written permission.
256   
257 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
258 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
259 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
260 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
261 HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
262 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
263 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
264 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
265 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
266 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
267 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
268
269== Version History
270
271; 1.0 : ported and simplyfied from chicken-4 version 1.4.1
Note: See TracBrowser for help on using the repository browser.