source: project/wiki/eggref/4/continuations @ 32683

Last change on this file since 32683 was 32683, checked in by juergen, 5 years ago

docu of continuations 1.3

File size: 7.8 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== continuations
5
6This library contains two modules, continuations and continuations-used.
7
8The former provides some syntactic sugar to Marc Feeley's continuation
9interface. In this 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 modules written in the design-by-contract style, the call
24(continuations) lists the exported symbols, and (continuations sym)
25provides documentation of the exported symbol sym.
26
27Moreover, another interface to continuations is provided, recommended by
28Matt Might, albeit with different names: current and the infamous
29goto. The former makes possible code written in an idiom similar to the
30setjmp-longjmp-pair in C, the latter, although dangerous, is sometimes
31useful, e.g. in backtracking ....
32 
33The second module, continuations-used, provides some applications of the
34continuations module.
35
36=== The routines of the continuations module
37
38==== continuations
39
40<procedure>(continuations [sym])</procedure>
41
42documentation procedure
43
44==== continuation
45
46<procedure>(continuation)</procedure>
47
48deprecated, use current instead.
49
50==== current
51
52<procedure>(current)</procedure>
53
54captures and returns the current continuation. Typically used as follows
55
56<enscript highlight=scheme>
57(let ((cc (current)))
58  (if (continuation? cc)
59    ... (throw cc val) ...
60    ... do something with val ...))
61</enscript>
62
63Note, that the let is invoked twice, first after the call to
64continuation, then with the object val, which was thrown to cc.
65
66==== continuation?
67
68<procedure>(continuation? xpr)</procedure>
69
70type predicate
71
72==== continuation->procedure
73
74<procedure>(continuation->procedure cont)</procedure>
75
76transforms a continuation into a procedure
77
78==== capture
79
80<procedure>(capture proc)</procedure>
81
82The same as call/cc but with a different datatype:
83Captures the current continuation as a continuation datatype (contrary
84to a procedure datatype in call/cc) and calls proc with that
85continuation as its only argument.
86
87==== graft
88
89<procedure>(graft cont thunk)</procedure>
90
91tail-calls thunk with the implicit continuation cont.
92
93==== throw
94
95<procedure>(throw cont . vals)</procedure>
96
97throws the values vals to the continuation cont.
98
99==== catch
100
101<macro>(catch cont xpr . xprs)</macro>
102
103The same as let/cc of miscmacros but with a different datatype:
104Binds the cont variable to the current continuation as a continuation
105and executes the body xpr .  xprs in this context. Typically used as
106follows
107 
108<enscript highlight=scheme>
109(catch k
110  ...
111  (if ...
112    (throw k val)
113    ...))
114</enscript>
115
116==== goto
117
118<procedure>(goto cc)</procedure>
119
120The infamous goto, but with a continuation as argument instead of a label.
121
122==== call
123
124<procedure>(call receiver)</procedure>
125
126The same as call/cc, but implemented via capture.
127
128=== The routines of the continuations-used module
129
130==== continuations-used
131
132<procedure>(continuations-used [sym])</procedure>
133
134the usual documentation procedure
135
136==== make-amb
137
138<procedure>(make-amb)</procedure>
139
140produces an ambiguous choice object, which accepts three messages,
141'choose, 'fail and 'assert.
142
143==== make-threads
144
145<procedure>(make-threads)</procedure>
146
147produces a threads object, which accepts five messages,
148'halt, 'quit, 'spawn, 'yield and 'start, implementing cooperative
149threads.
150
151==== iterate
152
153<macro>(iterate var iterator xpr . xprs)</macro>
154
155iterates var over iterater and applies the body, xpr . xprs, to each
156item. iterator should be a curried procedure of a container and a yield
157routine, the latter supplying one value at each pass.
158
159=== Examples
160
161==== amb
162
163<enscript highlight=scheme>
164(require-library continuations)
165(import continuations continuations-used)
166
167(define amb (make-amb))
168
169(define (pythagoras . choices)
170  (let ((a (apply (amb 'choose) choices))
171        (b (apply (amb 'choose) choices))
172        (c (apply (amb 'choose) choices)))
173    ((amb 'assert) (= (* c c) (+ (* a a) (* b b))))
174    ((amb 'assert) (< b a))
175    (list a b c)))
176
177(pythagoras 1 2 3 4 5 6 7) ; -> (4 3 5)
178</enscript>
179
180==== cooperative threads
181
182<enscript highlight=scheme>
183(require-library continuations)
184(import continuations continuations-used)
185
186(define threads (make-threads))
187
188(define make-thunk
189        (let ((counter 10))
190                (lambda (name)
191                        (rec (loop)
192                                (if (< counter 0)
193                                        ((threads 'quit)))
194                                (print (cons name counter))
195                                (set! counter (- counter 1))
196                                ((threads 'yield))
197                                (loop)))))
198
199((threads 'spawn) (make-thunk 'a))
200((threads 'spawn) (make-thunk 'aa))
201((threads 'spawn) (make-thunk 'aaa))
202((threads 'start))
203
204; prints (a . 10) (aa . 9) (aaa . 8) (a . 7) (aa . 6) (aaa . 5)
205;        (a . 4) (aa .  3) (aaa . 2) (a . 1) (aa . 0)
206; in sequence
207</enscript>
208
209==== iterators
210
211<enscript highlight=scheme>
212(require-library continuations)
213(import continuations continuations-used)
214
215;; define an iterator for tree, i.e. a function of yield, which returns
216;; one tree-item at each pass
217(define (tree-iterator tree)
218  (lambda (yield)
219    (let walk ((tree tree))
220      (if (pair? tree)
221        (begin (walk (car tree))
222               (walk (cdr tree)))
223        (yield tree)))))
224
225(iterate var (tree-iterator '(3 . ((4 . 5) . 6))) (print var))
226; prints 3 4 5 6 in sequence
227</enscript>
228
229== Requirements
230
231none
232
233== Last update
234
235Aug 09. 2015
236
237== Author
238
239[[/users/juergen-lorenz|Juergen Lorenz]]
240
241== License
242
243 Copyright (c) 2013, Juergen Lorenz
244 All rights reserved.
245
246 Redistribution and use in source and binary forms, with or without
247 modification, are permitted provided that the following conditions are
248 met:
249 
250 Redistributions of source code must retain the above copyright
251 notice, this list of conditions and the following disclaimer.
252 
253 Redistributions in binary form must reproduce the above copyright
254 notice, this list of conditions and the following disclaimer in the
255 documentation and/or other materials provided with the distribution.
256 Neither the name of the author nor the names of its contributors may be
257 used to endorse or promote products derived from this software without
258 specific prior written permission.
259   
260 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
261 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
262 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
263 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
264 HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
265 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
266 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
267 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
268 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
269 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
270 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
271
272== Version History
273
274; 1.3 : continuation renamed current, call added
275; 1.2.4 : tests updated
276; 1.2.2 : tests updated
277; 1.2.1 : bug in setup file corrected
278; 1.2 : some tests rewritten and repackeged as an extra module continuations-used
279; 1.1.2 : test cases for iterators and cooperative threads added
280; 1.1.1 : bug fix in documentation procedure
281; 1.1 : added continuation and goto with the amb example
282; 1.0 : initial import
Note: See TracBrowser for help on using the repository browser.