/[guile]/guile/guile-core/doc/ref/scheme-control.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/scheme-control.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.10 by kryde, Wed Jul 23 23:53:39 2003 UTC revision 1.11 by kryde, Thu Jul 24 00:30:31 2003 UTC
# Line 249  times. Line 249  times.
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

Legend:
Removed from v.1.10  
changed lines
  Added in v.1.11

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26