249 |
|
|
250 |
@node Continuations |
@node Continuations |
251 |
@section Continuations |
@section Continuations |
252 |
|
@cindex continuations |
253 |
|
|
254 |
@cindex call/cc |
A ``continuation'' is the code that will execute when a given function |
255 |
@cindex call-with-current-continuation |
or expression returns. For example, consider |
256 |
The ability to explicitly capture continuations using |
|
257 |
@code{call-with-current-continuation} (also often called @code{call/cc} |
@example |
258 |
for short), and to invoke such continuations later any number of times, |
(define (foo) |
259 |
and from any other point in a program, provides maybe the most powerful |
(display "hello\n") |
260 |
control structure known. All other control structures, such as loops |
(display (bar)) (newline) |
261 |
and coroutines, can be emulated using continuations. |
(exit)) |
262 |
|
@end example |
263 |
@c NJFIXME - need a little something here about what continuations are |
|
264 |
@c and what they do for you. |
The continuation from the call to @code{bar} comprises a |
265 |
|
@code{display} of the value returned, a @code{newline} and an |
266 |
The implementation of continuations in Guile is not as efficient as one |
@code{exit}. This can be expressed as a function of one argument. |
267 |
might hope, because it is constrained by the fact that Guile is designed |
|
268 |
to cooperate with programs written in other languages, such as C, which |
@example |
269 |
do not know about continuations. So continuations should be used when |
(lambda (r) |
270 |
there is no other simple way of achieving the desired behaviour, or |
(display r) (newline) |
271 |
where the advantages of the elegant continuation mechanism outweigh the |
(exit)) |
272 |
need for optimum performance. If you find yourself using @code{call/cc} |
@end example |
273 |
for escape procedures and your program is running too slow, you might |
|
274 |
want to use exceptions (@pxref{Exceptions}) instead. |
In Scheme, continuations are represented as special procedures just |
275 |
|
like this. The special property is that when a continuation is called |
276 |
|
it abandons the current program location and jumps directly to that |
277 |
|
represented by the continuation. |
278 |
|
|
279 |
|
A continuation is like a dynamic label, capturing at run-time a point |
280 |
|
in program execution, including all the nested calls that have lead to |
281 |
|
it, or rather the code that will execute when those calls return. |
282 |
|
|
283 |
|
Continuations are created with the following functions. |
284 |
|
|
|
@rnindex call-with-current-continuation |
|
285 |
@deffn {Scheme Procedure} call-with-current-continuation proc |
@deffn {Scheme Procedure} call-with-current-continuation proc |
286 |
Capture the current continuation and call @var{proc} with the captured |
@deffnx {Scheme Procedure} call/cc proc |
287 |
continuation as the single argument. This continuation can then be |
@rnindex call-with-current-continuation |
288 |
called with arbitrarily many arguments. Such a call will work like a |
Capture the current continuation and call @code{(@var{proc} |
289 |
goto to the invocation location of |
@var{cont})} with it. The return value is the value returned by |
290 |
@code{call-with-current-continuation}, passing the arguments in a way |
@var{proc}, or when @code{(@var{cont} @var{value})} is later invoked, |
291 |
that they are returned by the call to |
the return is the @var{value} passed. |
292 |
@code{call-with-current-continuation}. Since it is legal to store the |
|
293 |
captured continuation in a variable or to pass it to other procedures, |
Normally @var{cont} should be called with one argument, but when the |
294 |
it is possible that a procedure returns more than once, even if it is |
location resumed is expecting multiple values (@pxref{Multiple |
295 |
called only one time. This can be confusing at times. |
Values}) then they should be passed as multiple arguments, for |
296 |
|
instance @code{(@var{cont} @var{x} @var{y} @var{z})}. |
297 |
|
|
298 |
|
@var{cont} may only be used from the dynamic root in which it was |
299 |
|
created (@pxref{Dynamic Roots}), and in a multi-threaded program only |
300 |
|
from the thread in which it was created, since each thread is a |
301 |
|
separate dynamic root. |
302 |
|
|
303 |
|
The call to @var{proc} is not part of the continuation captured, it |
304 |
|
runs only when the continuation is created. Often a program will want |
305 |
|
to store @var{cont} somewhere for later use, this can be done in |
306 |
|
@var{proc}. |
307 |
|
|
308 |
|
The @code{call} in the name @code{call-with-current-continuation} |
309 |
|
refers to the way a call to @var{proc} gives the newly created |
310 |
|
continuation. It's not related to the way a call is used later to |
311 |
|
invoke that continuation. |
312 |
|
|
313 |
|
@code{call/cc} is an alias for @code{call-with-current-continuation}. |
314 |
|
This is in common use since the latter is rather long. |
315 |
@end deffn |
@end deffn |
316 |
|
|
317 |
@c FIXME::martin: Better example needed. |
@deftypefn {C Function} SCM scm_make_continuation (int *first) |
318 |
@lisp |
Capture the current continuation as described above. The return value |
319 |
|
is the new continuation, and @var{*first} is set to 1. |
320 |
|
|
321 |
|
When the continuation is invoked, @code{scm_make_continuation} will |
322 |
|
return again, this time returning the value (or set of multiple |
323 |
|
values) passed in that invocation, and with @var{*first} set to 0. |
324 |
|
@end deftypefn |
325 |
|
|
326 |
|
@sp 1 |
327 |
|
@noindent |
328 |
|
Here is a simple example, |
329 |
|
|
330 |
|
@example |
331 |
(define kont #f) |
(define kont #f) |
332 |
(call-with-current-continuation |
(format #t "the return is ~a\n" |
333 |
(lambda (k) |
(call/cc (lambda (k) |
334 |
(set! kont k) |
(set! kont k) |
335 |
1)) |
1))) |
336 |
@result{} |
@result{} the return is 1 |
|
1 |
|
337 |
|
|
338 |
(kont 2) |
(kont 2) |
339 |
@result{} |
@result{} the return is 2 |
340 |
2 |
@end example |
341 |
@end lisp |
|
342 |
|
@code{call/cc} captures a continuation in which the value returned is |
343 |
|
going to be displayed by @code{format}. The @code{lambda} stores this |
344 |
|
in @code{kont} and gives an initial return @code{1} which is |
345 |
|
displayed. The later invocation of @code{kont} resumes the captured |
346 |
|
point, but this time returning @code{2}, which is displayed. |
347 |
|
|
348 |
|
When Guile is run interactively, a call to @code{format} like this has |
349 |
|
an implicit return back to the read-eval-print loop. @code{call/cc} |
350 |
|
captures that like any other return, which is why interactively |
351 |
|
@code{kont} will come back to read more input. |
352 |
|
|
353 |
|
@sp 1 |
354 |
|
C programmers may note that @code{call/cc} is like @code{setjmp} in |
355 |
|
the way it records at runtime a point in program execution. A call to |
356 |
|
a continuation is like a @code{longjmp} in that it abandons the |
357 |
|
present location and goes to the recorded one. Like @code{longjmp}, |
358 |
|
the value passed to the continuation is the value returned by |
359 |
|
@code{call/cc} on resuming there. However @code{longjmp} can only go |
360 |
|
up the program stack, but the continuation mechanism can go anywhere. |
361 |
|
|
362 |
|
When a continuation is invoked, @code{call/cc} and subsequent code |
363 |
|
effectively ``returns'' a second time. It can be confusing to imagine |
364 |
|
a function returning more times than it was called. It may help |
365 |
|
instead to think of it being stealthily re-entered and then program |
366 |
|
flow going on as normal. |
367 |
|
|
368 |
|
@code{dynamic-wind} (@pxref{Dynamic Wind}) can be used to ensure setup |
369 |
|
and cleanup code is run when a program locus is resumed or abandoned |
370 |
|
through the continuation mechanism. For instance locking and |
371 |
|
unlocking database records in use, or similar. |
372 |
|
|
373 |
|
@sp 1 |
374 |
|
Continuations are a powerful mechanism, and can be used to implement |
375 |
|
almost any sort of control structure, such as loops, coroutines, or |
376 |
|
exception handlers. |
377 |
|
|
378 |
|
However the implementation of continuations in Guile is not as |
379 |
|
efficient as one might hope, because Guile is designed to cooperate |
380 |
|
with programs written in other languages, such as C, which do not know |
381 |
|
about continuations. Basically continuations are captured by a block |
382 |
|
copy of the stack, and resumed by copying back. |
383 |
|
|
384 |
|
For this reason, generally continuations should be used only when |
385 |
|
there is no other simple way to achieve the desired result, or when |
386 |
|
the elegance of the continuation mechanism outweighs the need for |
387 |
|
performance. |
388 |
|
|
389 |
|
Escapes upwards from loops or nested functions are generally best |
390 |
|
handled with exceptions (@pxref{Exceptions}). Coroutines can be |
391 |
|
efficiently implemented with cooperating threads (a thread holds a |
392 |
|
full program stack but doesn't copy it around the way continuations |
393 |
|
do). |
394 |
|
|
395 |
|
|
396 |
@node Multiple Values |
@node Multiple Values |