2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010,
4 @c 2011, 2012, 2013, 2014 Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
7 @node Control Mechanisms
8 @section Controlling the Flow of Program Execution
10 See @ref{Control Flow} for a discussion of how the more general control
11 flow of Scheme affects C code.
14 * begin:: Sequencing and splicing.
15 * Conditionals:: If, when, unless, case, and cond.
16 * and or:: Conditional evaluation of a sequence.
17 * while do:: Iteration mechanisms.
18 * Prompts:: Composable, delimited continuations.
19 * Continuations:: Non-composable continuations.
20 * Multiple Values:: Returning and accepting multiple values.
21 * Exceptions:: Throwing and catching exceptions.
22 * Error Reporting:: Procedures for signaling errors.
23 * Dynamic Wind:: Dealing with non-local entrance/exit.
24 * Handling Errors:: How to handle errors in C code.
25 * Continuation Barriers:: Protection from non-local control flow.
29 @subsection Sequencing and Splicing
33 @cindex expression sequencing
35 As an expression, the @code{begin} syntax is used to evaluate a sequence
36 of sub-expressions in order. Consider the conditional expression below:
40 (begin (display "greater") (newline)))
43 If the test is true, we want to display ``greater'' to the current
44 output port, then display a newline. We use @code{begin} to form a
45 compound expression out of this sequence of sub-expressions.
47 @deffn syntax begin expr @dots{}
48 The expression(s) are evaluated in left-to-right order and the value of
49 the last expression is returned as the value of the
50 @code{begin}-expression. This expression type is used when the
51 expressions before the last one are evaluated for their side effects.
55 @cindex definition splicing
57 The @code{begin} syntax has another role in definition context
58 (@pxref{Internal Definitions}). A @code{begin} form in a definition
59 context @dfn{splices} its subforms into its place. For example,
60 consider the following procedure:
64 (define-sealant seal open)
68 Let us assume the existence of a @code{define-sealant} macro that
69 expands out to some definitions wrapped in a @code{begin}, like so:
79 (and (pair? x) (eq? (car x) seal-tag)))
83 (error "Expected a sealed value:" x))))
87 Here, because the @code{begin} is in definition context, its subforms
88 are @dfn{spliced} into the place of the @code{begin}. This allows the
89 definitions created by the macro to be visible to the following
90 expression, the @code{values} form.
92 It is a fine point, but splicing and sequencing are different. It can
93 make sense to splice zero forms, because it can make sense to have zero
94 internal definitions before the expressions in a procedure or lexical
95 binding form. However it does not make sense to have a sequence of zero
96 expressions, because in that case it would not be clear what the value
97 of the sequence would be, because in a sequence of zero expressions,
98 there can be no last value. Sequencing zero expressions is an error.
100 It would be more elegant in some ways to eliminate splicing from the
101 Scheme language, and without macros (@pxref{Macros}), that would be a
102 good idea. But it is useful to be able to write macros that expand out
103 to multiple definitions, as in @code{define-sealant} above, so Scheme
104 abuses the @code{begin} form for these two tasks.
107 @subsection Simple Conditional Evaluation
109 @cindex conditional evaluation
116 Guile provides three syntactic constructs for conditional evaluation.
117 @code{if} is the normal if-then-else expression (with an optional else
118 branch), @code{cond} is a conditional expression with multiple branches
119 and @code{case} branches if an expression has one of a set of constant
122 @deffn syntax if test consequent [alternate]
123 All arguments may be arbitrary expressions. First, @var{test} is
124 evaluated. If it returns a true value, the expression @var{consequent}
125 is evaluated and @var{alternate} is ignored. If @var{test} evaluates to
126 @code{#f}, @var{alternate} is evaluated instead. The values of the
127 evaluated branch (@var{consequent} or @var{alternate}) are returned as
128 the values of the @code{if} expression.
130 When @var{alternate} is omitted and the @var{test} evaluates to
131 @code{#f}, the value of the expression is not specified.
134 When you go to write an @code{if} without an alternate (a @dfn{one-armed
135 @code{if}}), part of what you are expressing is that you don't care
136 about the return value (or values) of the expression. As such, you are
137 more interested in the @emph{effect} of evaluating the consequent
138 expression. (By convention, we use the word @dfn{statement} to refer to
139 an expression that is evaluated for effect, not for value).
141 In such a case, it is considered more clear to express these intentions
142 with these special forms, @code{when} and @code{unless}. As an added
143 bonus, these forms accept multiple statements to evaluate, which are
144 implicitly wrapped in a @code{begin}.
146 @deffn {Scheme Syntax} when test statement1 statement2 ...
147 @deffnx {Scheme Syntax} unless test statement1 statement2 ...
148 The actual definitions of these forms are in many ways their most clear
152 (define-syntax-rule (when test stmt stmt* ...)
153 (if test (begin stmt stmt* ...)))
155 (define-syntax-rule (unless condition stmt stmt* ...)
156 (if (not test) (begin stmt stmt* ...)))
159 That is to say, @code{when} evaluates its consequent statements in order
160 if @var{test} is true. @code{unless} is the opposite: it evaluates the
161 statements if @var{test} is false.
164 @deffn syntax cond clause1 clause2 @dots{}
165 Each @code{cond}-clause must look like this:
168 (@var{test} @var{expression} @dots{})
171 where @var{test} and @var{expression} are arbitrary expression, or like
175 (@var{test} => @var{expression})
178 where @var{expression} must evaluate to a procedure.
180 The @var{test}s of the clauses are evaluated in order and as soon as one
181 of them evaluates to a true values, the corresponding @var{expression}s
182 are evaluated in order and the last value is returned as the value of
183 the @code{cond}-expression. For the @code{=>} clause type,
184 @var{expression} is evaluated and the resulting procedure is applied to
185 the value of @var{test}. The result of this procedure application is
186 then the result of the @code{cond}-expression.
189 @cindex general cond clause
190 @cindex multiple values and cond
191 One additional @code{cond}-clause is available as an extension to
195 (@var{test} @var{guard} => @var{expression})
198 where @var{guard} and @var{expression} must evaluate to procedures.
199 For this clause type, @var{test} may return multiple values, and
200 @code{cond} ignores its boolean state; instead, @code{cond} evaluates
201 @var{guard} and applies the resulting procedure to the value(s) of
202 @var{test}, as if @var{guard} were the @var{consumer} argument of
203 @code{call-with-values}. If the result of that procedure call is a
204 true value, it evaluates @var{expression} and applies the resulting
205 procedure to the value(s) of @var{test}, in the same manner as the
206 @var{guard} was called.
208 The @var{test} of the last @var{clause} may be the symbol @code{else}.
209 Then, if none of the preceding @var{test}s is true, the
210 @var{expression}s following the @code{else} are evaluated to produce the
211 result of the @code{cond}-expression.
214 @deffn syntax case key clause1 clause2 @dots{}
215 @var{key} may be any expression, and the @var{clause}s must have the form
218 ((@var{datum1} @dots{}) @var{expr1} @var{expr2} @dots{})
224 ((@var{datum1} @dots{}) => @var{expression})
227 and the last @var{clause} may have the form
230 (else @var{expr1} @var{expr2} @dots{})
236 (else => @var{expression})
239 All @var{datum}s must be distinct. First, @var{key} is evaluated. The
240 result of this evaluation is compared against all @var{datum} values using
241 @code{eqv?}. When this comparison succeeds, the expression(s) following
242 the @var{datum} are evaluated from left to right, returning the value of
243 the last expression as the result of the @code{case} expression.
245 If the @var{key} matches no @var{datum} and there is an
246 @code{else}-clause, the expressions following the @code{else} are
247 evaluated. If there is no such clause, the result of the expression is
250 For the @code{=>} clause types, @var{expression} is evaluated and the
251 resulting procedure is applied to the value of @var{key}. The result of
252 this procedure application is then the result of the
253 @code{case}-expression.
258 @subsection Conditional Evaluation of a Sequence of Expressions
260 @code{and} and @code{or} evaluate all their arguments in order, similar
261 to @code{begin}, but evaluation stops as soon as one of the expressions
262 evaluates to false or true, respectively.
264 @deffn syntax and expr @dots{}
265 Evaluate the @var{expr}s from left to right and stop evaluation as soon
266 as one expression evaluates to @code{#f}; the remaining expressions are
267 not evaluated. The value of the last evaluated expression is returned.
268 If no expression evaluates to @code{#f}, the value of the last
269 expression is returned.
271 If used without expressions, @code{#t} is returned.
274 @deffn syntax or expr @dots{}
275 Evaluate the @var{expr}s from left to right and stop evaluation as soon
276 as one expression evaluates to a true value (that is, a value different
277 from @code{#f}); the remaining expressions are not evaluated. The value
278 of the last evaluated expression is returned. If all expressions
279 evaluate to @code{#f}, @code{#f} is returned.
281 If used without expressions, @code{#f} is returned.
286 @subsection Iteration mechanisms
292 Scheme has only few iteration mechanisms, mainly because iteration in
293 Scheme programs is normally expressed using recursion. Nevertheless,
294 R5RS defines a construct for programming loops, calling @code{do}. In
295 addition, Guile has an explicit looping syntax called @code{while}.
297 @deffn syntax do ((variable init [step]) @dots{}) (test expr @dots{}) body @dots{}
298 Bind @var{variable}s and evaluate @var{body} until @var{test} is true.
299 The return value is the last @var{expr} after @var{test}, if given. A
300 simple example will illustrate the basic form,
310 Or with two variables and a final return value,
317 (format #t "3**~s is ~s\n" i p))
327 The @var{variable} bindings are established like a @code{let}, in that
328 the expressions are all evaluated and then all bindings made. When
329 iterating, the optional @var{step} expressions are evaluated with the
330 previous bindings in scope, then new bindings all made.
332 The @var{test} expression is a termination condition. Looping stops
333 when the @var{test} is true. It's evaluated before running the
334 @var{body} each time, so if it's true the first time then @var{body}
337 The optional @var{expr}s after the @var{test} are evaluated at the end
338 of looping, with the final @var{variable} bindings available. The
339 last @var{expr} gives the return value, or if there are no @var{expr}s
340 the return value is unspecified.
342 Each iteration establishes bindings to fresh locations for the
343 @var{variable}s, like a new @code{let} for each iteration. This is
344 done for @var{variable}s without @var{step} expressions too. The
345 following illustrates this, showing how a new @code{i} is captured by
346 the @code{lambda} in each iteration (@pxref{About Closure,, The
347 Concept of Closure}).
353 (set! lst (cons (lambda () i) lst)))
354 (map (lambda (proc) (proc)) lst)
360 @deffn syntax while cond body @dots{}
361 Run a loop executing the @var{body} forms while @var{cond} is true.
362 @var{cond} is tested at the start of each iteration, so if it's
363 @code{#f} the first time then @var{body} is not executed at all.
365 Within @code{while}, two extra bindings are provided, they can be used
366 from both @var{cond} and @var{body}.
368 @deffn {Scheme Procedure} break break-arg @dots{}
369 Break out of the @code{while} form.
372 @deffn {Scheme Procedure} continue
373 Abandon the current iteration, go back to the start and test
374 @var{cond} again, etc.
377 If the loop terminates normally, by the @var{cond} evaluating to
378 @code{#f}, then the @code{while} expression as a whole evaluates to
379 @code{#f}. If it terminates by a call to @code{break} with some number
380 of arguments, those arguments are returned from the @code{while}
381 expression, as multiple values. Otherwise if it terminates by a call to
382 @code{break} with no arguments, then return value is @code{#t}.
385 (while #f (error "not reached")) @result{} #f
386 (while #t (break)) @result{} #t
387 (while #t (break 1 2 3)) @result{} 1 2 3
390 Each @code{while} form gets its own @code{break} and @code{continue}
391 procedures, operating on that @code{while}. This means when loops are
392 nested the outer @code{break} can be used to escape all the way out.
397 (let ((outer-break break))
404 Note that each @code{break} and @code{continue} procedure can only be
405 used within the dynamic extent of its @code{while}. Outside the
406 @code{while} their behaviour is unspecified.
410 Another very common way of expressing iteration in Scheme programs is
411 the use of the so-called @dfn{named let}.
413 Named let is a variant of @code{let} which creates a procedure and calls
414 it in one step. Because of the newly created procedure, named let is
415 more powerful than @code{do}--it can be used for iteration, but also
416 for arbitrary recursion.
418 @deffn syntax let variable bindings body
419 For the definition of @var{bindings} see the documentation about
420 @code{let} (@pxref{Local Bindings}).
422 Named @code{let} works as follows:
426 A new procedure which accepts as many arguments as are in @var{bindings}
427 is created and bound locally (using @code{let}) to @var{variable}. The
428 new procedure's formal argument names are the name of the
432 The @var{body} expressions are inserted into the newly created procedure.
435 The procedure is called with the @var{init} expressions as the formal
439 The next example implements a loop which iterates (by recursion) 1000
456 @cindex delimited continuations
457 @cindex composable continuations
458 @cindex non-local exit
460 Prompts are control-flow barriers between different parts of a program. In the
461 same way that a user sees a shell prompt (e.g., the Bash prompt) as a barrier
462 between the operating system and her programs, Scheme prompts allow the Scheme
463 programmer to treat parts of programs as if they were running in different
466 We use this roundabout explanation because, unless you're a functional
467 programming junkie, you probably haven't heard the term, ``delimited, composable
468 continuation''. That's OK; it's a relatively recent topic, but a very useful
472 * Prompt Primitives:: Call-with-prompt and abort-to-prompt.
473 * Shift and Reset:: The zoo of delimited control operators.
476 @node Prompt Primitives
477 @subsubsection Prompt Primitives
479 Guile's primitive delimited control operators are
480 @code{call-with-prompt} and @code{abort-to-prompt}.
482 @deffn {Scheme Procedure} call-with-prompt tag thunk handler
483 Set up a prompt, and call @var{thunk} within that prompt.
485 During the dynamic extent of the call to @var{thunk}, a prompt named @var{tag}
486 will be present in the dynamic context, such that if a user calls
487 @code{abort-to-prompt} (see below) with that tag, control rewinds back to the
488 prompt, and the @var{handler} is run.
490 @var{handler} must be a procedure. The first argument to @var{handler} will be
491 the state of the computation begun when @var{thunk} was called, and ending with
492 the call to @code{abort-to-prompt}. The remaining arguments to @var{handler} are
493 those passed to @code{abort-to-prompt}.
496 @deffn {Scheme Procedure} make-prompt-tag [stem]
497 Make a new prompt tag. A prompt tag is simply a unique object.
498 Currently, a prompt tag is a fresh pair. This may change in some future
502 @deffn {Scheme Procedure} default-prompt-tag
503 Return the default prompt tag. Having a distinguished default prompt
504 tag allows some useful prompt and abort idioms, discussed in the next
505 section. Note that @code{default-prompt-tag} is actually a parameter,
506 and so may be dynamically rebound using @code{parameterize}.
510 @deffn {Scheme Procedure} abort-to-prompt tag val1 val2 @dots{}
511 Unwind the dynamic and control context to the nearest prompt named @var{tag},
512 also passing the given values.
515 C programmers may recognize @code{call-with-prompt} and @code{abort-to-prompt}
516 as a fancy kind of @code{setjmp} and @code{longjmp}, respectively. Prompts are
517 indeed quite useful as non-local escape mechanisms. Guile's @code{catch} and
518 @code{throw} are implemented in terms of prompts. Prompts are more convenient
519 than @code{longjmp}, in that one has the opportunity to pass multiple values to
522 Also unlike @code{longjmp}, the prompt handler is given the full state of the
523 process that was aborted, as the first argument to the prompt's handler. That
524 state is the @dfn{continuation} of the computation wrapped by the prompt. It is
525 a @dfn{delimited continuation}, because it is not the whole continuation of the
526 program; rather, just the computation initiated by the call to
527 @code{call-with-prompt}.
529 The continuation is a procedure, and may be reinstated simply by invoking it,
530 with any number of values. Here's where things get interesting, and complicated
531 as well. Besides being described as delimited, continuations reified by prompts
532 are also @dfn{composable}, because invoking a prompt-saved continuation composes
533 that continuation with the current one.
535 Imagine you have saved a continuation via call-with-prompt:
544 (+ 34 (abort-to-prompt 'foo)))
549 The resulting continuation is the addition of 34. It's as if you had written:
557 So, if we call @code{cont} with one numeric value, we get that number,
567 The last example illustrates what we mean when we say, "composes with the
568 current continuation". We mean that there is a current continuation -- some
569 remaining things to compute, like @code{(lambda (x) (* x 2))} -- and that
570 calling the saved continuation doesn't wipe out the current continuation, it
571 composes the saved continuation with the current one.
573 We're belaboring the point here because traditional Scheme continuations, as
574 discussed in the next section, aren't composable, and are actually less
575 expressive than continuations captured by prompts. But there's a place for them
578 Before moving on, we should mention that if the handler of a prompt is a
579 @code{lambda} expression, and the first argument isn't referenced, an abort to
580 that prompt will not cause a continuation to be reified. This can be an
581 important efficiency consideration to keep in mind.
583 @cindex continuation, escape
584 One example where this optimization matters is @dfn{escape
585 continuations}. Escape continuations are delimited continuations whose
586 only use is to make a non-local exit---i.e., to escape from the current
587 continuation. Such continuations are invoked only once, and for this
588 reason they are sometimes called @dfn{one-shot continuations}. A common
589 use of escape continuations is when throwing an exception
590 (@pxref{Exceptions}).
592 The constructs below are syntactic sugar atop prompts to simplify the
593 use of escape continuations.
595 @deffn {Scheme Procedure} call-with-escape-continuation proc
596 @deffnx {Scheme Procedure} call/ec proc
597 Call @var{proc} with an escape continuation.
599 In the example below, the @var{return} continuation is used to escape
600 the continuation of the call to @code{fold}.
603 (use-modules (ice-9 control)
606 (define (prefix x lst)
607 ;; Return all the elements before the first occurrence
611 (fold (lambda (element prefix)
612 (if (equal? element x)
613 (return (reverse prefix)) ; escape `fold'
614 (cons element prefix)))
618 (prefix 'a '(0 1 2 a 3 4 5))
623 @deffn {Scheme Syntax} let-escape-continuation k body @dots{}
624 @deffnx {Scheme Syntax} let/ec k body @dots{}
625 Bind @var{k} within @var{body} to an escape continuation.
627 This is equivalent to
628 @code{(call/ec (lambda (@var{k}) @var{body} @dots{}))}.
632 @node Shift and Reset
633 @subsubsection Shift, Reset, and All That
635 There is a whole zoo of delimited control operators, and as it does not
636 seem to be a bounded set, Guile implements support for them in a
640 (use-modules (ice-9 control))
643 Firstly, we have a helpful abbreviation for the @code{call-with-prompt}
646 @deffn {Scheme Syntax} % expr
647 @deffnx {Scheme Syntax} % expr handler
648 @deffnx {Scheme Syntax} % tag expr handler
649 Evaluate @var{expr} in a prompt, optionally specifying a tag and a
650 handler. If no tag is given, the default prompt tag is used.
652 If no handler is given, a default handler is installed. The default
653 handler accepts a procedure of one argument, which will called on the
654 captured continuation, within a prompt.
656 Sometimes it's easier just to show code, as in this case:
659 (define (default-prompt-handler k proc)
660 (% (default-prompt-tag)
662 default-prompt-handler))
665 The @code{%} symbol is chosen because it looks like a prompt.
668 Likewise there is an abbreviation for @code{abort-to-prompt}, which
669 assumes the default prompt tag:
671 @deffn {Scheme Procedure} abort val1 val2 @dots{}
672 Abort to the default prompt tag, passing @var{val1} @var{val2} @dots{}
676 As mentioned before, @code{(ice-9 control)} also provides other
677 delimited control operators. This section is a bit technical, and
678 first-time users of delimited continuations should probably come back to
679 it after some practice with @code{%}.
681 Still here? So, when one implements a delimited control operator like
682 @code{call-with-prompt}, one needs to make two decisions. Firstly, does
683 the handler run within or outside the prompt? Having the handler run
684 within the prompt allows an abort inside the handler to return to the
685 same prompt handler, which is often useful. However it prevents tail
686 calls from the handler, so it is less general.
688 Similarly, does invoking a captured continuation reinstate a prompt?
689 Again we have the tradeoff of convenience versus proper tail calls.
691 These decisions are captured in the Felleisen @dfn{F} operator. If
692 neither the continuations nor the handlers implicitly add a prompt, the
693 operator is known as @dfn{--F--}. This is the case for Guile's
694 @code{call-with-prompt} and @code{abort-to-prompt}.
696 If both continuation and handler implicitly add prompts, then the
697 operator is @dfn{+F+}. @code{shift} and @code{reset} are such
700 @deffn {Scheme Syntax} reset body1 body2 @dots{}
701 Establish a prompt, and evaluate @var{body1} @var{body2} @dots{} within
704 The prompt handler is designed to work with @code{shift}, described
708 @deffn {Scheme Syntax} shift cont body1 body2 @dots{}
709 Abort to the nearest @code{reset}, and evaluate @var{body1} @var{body2}
710 @dots{} in a context in which the captured continuation is bound to
713 As mentioned above, taken together, the @var{body1} @var{body2} @dots{}
714 expressions and the invocations of @var{cont} implicitly establish a
718 Interested readers are invited to explore Oleg Kiselyov's wonderful web
719 site at @uref{http://okmij.org/ftp/}, for more information on these
724 @subsection Continuations
725 @cindex continuations
727 A ``continuation'' is the code that will execute when a given function
728 or expression returns. For example, consider
733 (display (bar)) (newline)
737 The continuation from the call to @code{bar} comprises a
738 @code{display} of the value returned, a @code{newline} and an
739 @code{exit}. This can be expressed as a function of one argument.
743 (display r) (newline)
747 In Scheme, continuations are represented as special procedures just
748 like this. The special property is that when a continuation is called
749 it abandons the current program location and jumps directly to that
750 represented by the continuation.
752 A continuation is like a dynamic label, capturing at run-time a point
753 in program execution, including all the nested calls that have lead to
754 it (or rather the code that will execute when those calls return).
756 Continuations are created with the following functions.
758 @deffn {Scheme Procedure} call-with-current-continuation proc
759 @deffnx {Scheme Procedure} call/cc proc
760 @rnindex call-with-current-continuation
761 Capture the current continuation and call @code{(@var{proc}
762 @var{cont})} with it. The return value is the value returned by
763 @var{proc}, or when @code{(@var{cont} @var{value})} is later invoked,
764 the return is the @var{value} passed.
766 Normally @var{cont} should be called with one argument, but when the
767 location resumed is expecting multiple values (@pxref{Multiple
768 Values}) then they should be passed as multiple arguments, for
769 instance @code{(@var{cont} @var{x} @var{y} @var{z})}.
771 @var{cont} may only be used from the same side of a continuation
772 barrier as it was created (@pxref{Continuation Barriers}), and in a
773 multi-threaded program only from the thread in which it was created.
775 The call to @var{proc} is not part of the continuation captured, it runs
776 only when the continuation is created. Often a program will want to
777 store @var{cont} somewhere for later use; this can be done in
780 The @code{call} in the name @code{call-with-current-continuation}
781 refers to the way a call to @var{proc} gives the newly created
782 continuation. It's not related to the way a call is used later to
783 invoke that continuation.
785 @code{call/cc} is an alias for @code{call-with-current-continuation}.
786 This is in common use since the latter is rather long.
791 Here is a simple example,
795 (format #t "the return is ~a\n"
799 @result{} the return is 1
802 @result{} the return is 2
805 @code{call/cc} captures a continuation in which the value returned is
806 going to be displayed by @code{format}. The @code{lambda} stores this
807 in @code{kont} and gives an initial return @code{1} which is
808 displayed. The later invocation of @code{kont} resumes the captured
809 point, but this time returning @code{2}, which is displayed.
811 When Guile is run interactively, a call to @code{format} like this has
812 an implicit return back to the read-eval-print loop. @code{call/cc}
813 captures that like any other return, which is why interactively
814 @code{kont} will come back to read more input.
817 C programmers may note that @code{call/cc} is like @code{setjmp} in
818 the way it records at runtime a point in program execution. A call to
819 a continuation is like a @code{longjmp} in that it abandons the
820 present location and goes to the recorded one. Like @code{longjmp},
821 the value passed to the continuation is the value returned by
822 @code{call/cc} on resuming there. However @code{longjmp} can only go
823 up the program stack, but the continuation mechanism can go anywhere.
825 When a continuation is invoked, @code{call/cc} and subsequent code
826 effectively ``returns'' a second time. It can be confusing to imagine
827 a function returning more times than it was called. It may help
828 instead to think of it being stealthily re-entered and then program
829 flow going on as normal.
831 @code{dynamic-wind} (@pxref{Dynamic Wind}) can be used to ensure setup
832 and cleanup code is run when a program locus is resumed or abandoned
833 through the continuation mechanism.
836 Continuations are a powerful mechanism, and can be used to implement
837 almost any sort of control structure, such as loops, coroutines, or
840 However the implementation of continuations in Guile is not as
841 efficient as one might hope, because Guile is designed to cooperate
842 with programs written in other languages, such as C, which do not know
843 about continuations. Basically continuations are captured by a block
844 copy of the stack, and resumed by copying back.
846 For this reason, continuations captured by @code{call/cc} should be used only
847 when there is no other simple way to achieve the desired result, or when the
848 elegance of the continuation mechanism outweighs the need for performance.
850 Escapes upwards from loops or nested functions are generally best
851 handled with prompts (@pxref{Prompts}). Coroutines can be
852 efficiently implemented with cooperating threads (a thread holds a
853 full program stack but doesn't copy it around the way continuations
857 @node Multiple Values
858 @subsection Returning and Accepting Multiple Values
860 @cindex multiple values
863 Scheme allows a procedure to return more than one value to its caller.
864 This is quite different to other languages which only allow
865 single-value returns. Returning multiple values is different from
866 returning a list (or pair or vector) of values to the caller, because
867 conceptually not @emph{one} compound object is returned, but several
870 The primitive procedures for handling multiple values are @code{values}
871 and @code{call-with-values}. @code{values} is used for returning
872 multiple values from a procedure. This is done by placing a call to
873 @code{values} with zero or more arguments in tail position in a
874 procedure body. @code{call-with-values} combines a procedure returning
875 multiple values with a procedure which accepts these values as
879 @deffn {Scheme Procedure} values arg @dots{}
880 @deffnx {C Function} scm_values (args)
881 Delivers all of its arguments to its continuation. Except for
882 continuations created by the @code{call-with-values} procedure,
883 all continuations take exactly one value. The effect of
884 passing no value or more than one value to continuations that
885 were not created by @code{call-with-values} is unspecified.
887 For @code{scm_values}, @var{args} is a list of arguments and the
888 return is a multiple-values object which the caller can return. In
889 the current implementation that object shares structure with
890 @var{args}, so @var{args} should not be modified subsequently.
893 @deftypefn {C Function} SCM scm_c_values (SCM *base, size_t n)
894 @code{scm_c_values} is an alternative to @code{scm_values}. It creates
895 a new values object, and copies into it the @var{n} values starting from
898 Currently this creates a list and passes it to @code{scm_values}, but we
899 expect that in the future we will be able to use more a efficient
903 @deftypefn {C Function} size_t scm_c_nvalues (SCM obj)
904 If @var{obj} is a multiple-values object, returns the number of values
905 it contains. Otherwise returns 1.
908 @deftypefn {C Function} SCM scm_c_value_ref (SCM obj, size_t idx)
909 Returns the value at the position specified by @var{idx} in
910 @var{obj}. Note that @var{obj} will ordinarily be a
911 multiple-values object, but it need not be. Any other object
912 represents a single value (itself), and is handled appropriately.
915 @rnindex call-with-values
916 @deffn {Scheme Procedure} call-with-values producer consumer
917 Calls its @var{producer} argument with no values and a
918 continuation that, when passed some values, calls the
919 @var{consumer} procedure with those values as arguments. The
920 continuation for the call to @var{consumer} is the continuation
921 of the call to @code{call-with-values}.
924 (call-with-values (lambda () (values 4 5))
930 (call-with-values * -)
935 In addition to the fundamental procedures described above, Guile has a
936 module which exports a syntax called @code{receive}, which is much
937 more convenient. This is in the @code{(ice-9 receive)} and is the
938 same as specified by SRFI-8 (@pxref{SRFI-8}).
941 (use-modules (ice-9 receive))
944 @deffn {library syntax} receive formals expr body @dots{}
945 Evaluate the expression @var{expr}, and bind the result values (zero
946 or more) to the formal arguments in @var{formals}. @var{formals} is a
947 list of symbols, like the argument list in a @code{lambda}
948 (@pxref{Lambda}). After binding the variables, the expressions in
949 @var{body} @dots{} are evaluated in order, the return value is the
950 result from the last expression.
952 For example getting results from @code{partition} in SRFI-1
956 (receive (odds evens)
957 (partition odd? '(7 4 2 8 3))
961 @print{} (7 3) and (4 2 8)
968 @subsection Exceptions
969 @cindex error handling
970 @cindex exception handling
972 A common requirement in applications is to want to jump
973 @dfn{non-locally} from the depths of a computation back to, say, the
974 application's main processing loop. Usually, the place that is the
975 target of the jump is somewhere in the calling stack of procedures that
976 called the procedure that wants to jump back. For example, typical
977 logic for a key press driven application might look something like this:
981 read the next key press and call dispatch-key
984 lookup the key in a keymap and call an appropriate procedure,
988 interactively read the required file name, then call
992 check whether file exists; if not, jump back to main-loop
996 The jump back to @code{main-loop} could be achieved by returning through
997 the stack one procedure at a time, using the return value of each
998 procedure to indicate the error condition, but Guile (like most modern
999 programming languages) provides an additional mechanism called
1000 @dfn{exception handling} that can be used to implement such jumps much
1004 * Exception Terminology:: Different ways to say the same thing.
1005 * Catch:: Setting up to catch exceptions.
1006 * Throw Handlers:: Handling exceptions before unwinding the stack.
1007 * Throw:: Throwing an exception.
1008 * Exception Implementation:: How Guile implements exceptions.
1012 @node Exception Terminology
1013 @subsubsection Exception Terminology
1015 There are several variations on the terminology for dealing with
1016 non-local jumps. It is useful to be aware of them, and to realize
1017 that they all refer to the same basic mechanism.
1021 Actually making a non-local jump may be called @dfn{raising an
1022 exception}, @dfn{raising a signal}, @dfn{throwing an exception} or
1023 @dfn{doing a long jump}. When the jump indicates an error condition,
1024 people may talk about @dfn{signalling}, @dfn{raising} or @dfn{throwing}
1028 Handling the jump at its target may be referred to as @dfn{catching} or
1029 @dfn{handling} the @dfn{exception}, @dfn{signal} or, where an error
1030 condition is involved, @dfn{error}.
1033 Where @dfn{signal} and @dfn{signalling} are used, special care is needed
1034 to avoid the risk of confusion with POSIX signals.
1036 This manual prefers to speak of throwing and catching exceptions, since
1037 this terminology matches the corresponding Guile primitives.
1039 The exception mechanism described in this section has connections with
1040 @dfn{delimited continuations} (@pxref{Prompts}). In particular,
1041 throwing an exception is akin to invoking an @dfn{escape continuation}
1042 (@pxref{Prompt Primitives, @code{call/ec}}).
1046 @subsubsection Catching Exceptions
1048 @code{catch} is used to set up a target for a possible non-local jump.
1049 The arguments of a @code{catch} expression are a @dfn{key}, which
1050 restricts the set of exceptions to which this @code{catch} applies, a
1051 thunk that specifies the code to execute and one or two @dfn{handler}
1052 procedures that say what to do if an exception is thrown while executing
1053 the code. If the execution thunk executes @dfn{normally}, which means
1054 without throwing any exceptions, the handler procedures are not called
1057 When an exception is thrown using the @code{throw} function, the first
1058 argument of the @code{throw} is a symbol that indicates the type of the
1059 exception. For example, Guile throws an exception using the symbol
1060 @code{numerical-overflow} to indicate numerical overflow errors such as
1066 ABORT: (numerical-overflow)
1069 The @var{key} argument in a @code{catch} expression corresponds to this
1070 symbol. @var{key} may be a specific symbol, such as
1071 @code{numerical-overflow}, in which case the @code{catch} applies
1072 specifically to exceptions of that type; or it may be @code{#t}, which
1073 means that the @code{catch} applies to all exceptions, irrespective of
1076 The second argument of a @code{catch} expression should be a thunk
1077 (i.e.@: a procedure that accepts no arguments) that specifies the normal
1078 case code. The @code{catch} is active for the execution of this thunk,
1079 including any code called directly or indirectly by the thunk's body.
1080 Evaluation of the @code{catch} expression activates the catch and then
1083 The third argument of a @code{catch} expression is a handler procedure.
1084 If an exception is thrown, this procedure is called with exactly the
1085 arguments specified by the @code{throw}. Therefore, the handler
1086 procedure must be designed to accept a number of arguments that
1087 corresponds to the number of arguments in all @code{throw} expressions
1088 that can be caught by this @code{catch}.
1090 The fourth, optional argument of a @code{catch} expression is another
1091 handler procedure, called the @dfn{pre-unwind} handler. It differs from
1092 the third argument in that if an exception is thrown, it is called,
1093 @emph{before} the third argument handler, in exactly the dynamic context
1094 of the @code{throw} expression that threw the exception. This means
1095 that it is useful for capturing or displaying the stack at the point of
1096 the @code{throw}, or for examining other aspects of the dynamic context,
1097 such as fluid values, before the context is unwound back to that of the
1098 prevailing @code{catch}.
1100 @deffn {Scheme Procedure} catch key thunk handler [pre-unwind-handler]
1101 @deffnx {C Function} scm_catch_with_pre_unwind_handler (key, thunk, handler, pre_unwind_handler)
1102 @deffnx {C Function} scm_catch (key, thunk, handler)
1103 Invoke @var{thunk} in the dynamic context of @var{handler} for
1104 exceptions matching @var{key}. If thunk throws to the symbol
1105 @var{key}, then @var{handler} is invoked this way:
1107 (handler key args ...)
1110 @var{key} is a symbol or @code{#t}.
1112 @var{thunk} takes no arguments. If @var{thunk} returns
1113 normally, that is the return value of @code{catch}.
1115 Handler is invoked outside the scope of its own @code{catch}.
1116 If @var{handler} again throws to the same key, a new handler
1117 from further up the call chain is invoked.
1119 If the key is @code{#t}, then a throw to @emph{any} symbol will
1120 match this call to @code{catch}.
1122 If a @var{pre-unwind-handler} is given and @var{thunk} throws
1123 an exception that matches @var{key}, Guile calls the
1124 @var{pre-unwind-handler} before unwinding the dynamic state and
1125 invoking the main @var{handler}. @var{pre-unwind-handler} should
1126 be a procedure with the same signature as @var{handler}, that
1127 is @code{(lambda (key . args))}. It is typically used to save
1128 the stack at the point where the exception occurred, but can also
1129 query other parts of the dynamic state at that point, such as
1132 A @var{pre-unwind-handler} can exit either normally or non-locally.
1133 If it exits normally, Guile unwinds the stack and dynamic context
1134 and then calls the normal (third argument) handler. If it exits
1135 non-locally, that exit determines the continuation.
1138 If a handler procedure needs to match a variety of @code{throw}
1139 expressions with varying numbers of arguments, you should write it like
1143 (lambda (key . args)
1148 The @var{key} argument is guaranteed always to be present, because a
1149 @code{throw} without a @var{key} is not valid. The number and
1150 interpretation of the @var{args} varies from one type of exception to
1151 another, but should be specified by the documentation for each exception
1154 Note that, once the normal (post-unwind) handler procedure is invoked,
1155 the catch that led to the handler procedure being called is no longer
1156 active. Therefore, if the handler procedure itself throws an exception,
1157 that exception can only be caught by another active catch higher up the
1158 call stack, if there is one.
1161 @deftypefn {C Function} SCM scm_c_catch (SCM tag, scm_t_catch_body body, void *body_data, scm_t_catch_handler handler, void *handler_data, scm_t_catch_handler pre_unwind_handler, void *pre_unwind_handler_data)
1162 @deftypefnx {C Function} SCM scm_internal_catch (SCM tag, scm_t_catch_body body, void *body_data, scm_t_catch_handler handler, void *handler_data)
1163 The above @code{scm_catch_with_pre_unwind_handler} and @code{scm_catch}
1164 take Scheme procedures as body and handler arguments.
1165 @code{scm_c_catch} and @code{scm_internal_catch} are equivalents taking
1168 @var{body} is called as @code{@var{body} (@var{body_data})} with a catch
1169 on exceptions of the given @var{tag} type. If an exception is caught,
1170 @var{pre_unwind_handler} and @var{handler} are called as
1171 @code{@var{handler} (@var{handler_data}, @var{key}, @var{args})}.
1172 @var{key} and @var{args} are the @code{SCM} key and argument list from
1175 @tpindex scm_t_catch_body
1176 @tpindex scm_t_catch_handler
1177 @var{body} and @var{handler} should have the following prototypes.
1178 @code{scm_t_catch_body} and @code{scm_t_catch_handler} are pointer
1182 SCM body (void *data);
1183 SCM handler (void *data, SCM key, SCM args);
1186 The @var{body_data} and @var{handler_data} parameters are passed to
1187 the respective calls so an application can communicate extra
1188 information to those functions.
1190 If the data consists of an @code{SCM} object, care should be taken that
1191 it isn't garbage collected while still required. If the @code{SCM} is a
1192 local C variable, one way to protect it is to pass a pointer to that
1193 variable as the data parameter, since the C compiler will then know the
1194 value must be held on the stack. Another way is to use
1195 @code{scm_remember_upto_here_1} (@pxref{Foreign Object Memory
1200 @node Throw Handlers
1201 @subsubsection Throw Handlers
1203 It's sometimes useful to be able to intercept an exception that is being
1204 thrown before the stack is unwound. This could be to clean up some
1205 related state, to print a backtrace, or to pass information about the
1206 exception to a debugger, for example. The @code{with-throw-handler}
1207 procedure provides a way to do this.
1209 @deffn {Scheme Procedure} with-throw-handler key thunk handler
1210 @deffnx {C Function} scm_with_throw_handler (key, thunk, handler)
1211 Add @var{handler} to the dynamic context as a throw handler
1212 for key @var{key}, then invoke @var{thunk}.
1214 This behaves exactly like @code{catch}, except that it does not unwind
1215 the stack before invoking @var{handler}. If the @var{handler} procedure
1216 returns normally, Guile rethrows the same exception again to the next
1217 innermost catch or throw handler. @var{handler} may exit nonlocally, of
1218 course, via an explicit throw or via invoking a continuation.
1221 Typically @var{handler} is used to display a backtrace of the stack at
1222 the point where the corresponding @code{throw} occurred, or to save off
1223 this information for possible display later.
1225 Not unwinding the stack means that throwing an exception that is handled
1226 via a throw handler is equivalent to calling the throw handler handler
1227 inline instead of each @code{throw}, and then omitting the surrounding
1228 @code{with-throw-handler}. In other words,
1231 (with-throw-handler 'key
1232 (lambda () @dots{} (throw 'key args @dots{}) @dots{})
1237 is mostly equivalent to
1240 ((lambda () @dots{} (handler 'key args @dots{}) @dots{}))
1243 In particular, the dynamic context when @var{handler} is invoked is that
1244 of the site where @code{throw} is called. The examples are not quite
1245 equivalent, because the body of a @code{with-throw-handler} is not in
1246 tail position with respect to the @code{with-throw-handler}, and if
1247 @var{handler} exits normally, Guile arranges to rethrow the error, but
1248 hopefully the intention is clear. (For an introduction to what is meant
1249 by dynamic context, @xref{Dynamic Wind}.)
1251 @deftypefn {C Function} SCM scm_c_with_throw_handler (SCM tag, scm_t_catch_body body, void *body_data, scm_t_catch_handler handler, void *handler_data, int lazy_catch_p)
1252 The above @code{scm_with_throw_handler} takes Scheme procedures as body
1253 (thunk) and handler arguments. @code{scm_c_with_throw_handler} is an
1254 equivalent taking C functions. See @code{scm_c_catch} (@pxref{Catch})
1255 for a description of the parameters, the behaviour however of course
1256 follows @code{with-throw-handler}.
1259 If @var{thunk} throws an exception, Guile handles that exception by
1260 invoking the innermost @code{catch} or throw handler whose key matches
1261 that of the exception. When the innermost thing is a throw handler,
1262 Guile calls the specified handler procedure using @code{(apply
1263 @var{handler} key args)}. The handler procedure may either return
1264 normally or exit non-locally. If it returns normally, Guile passes the
1265 exception on to the next innermost @code{catch} or throw handler. If it
1266 exits non-locally, that exit determines the continuation.
1268 The behaviour of a throw handler is very similar to that of a
1269 @code{catch} expression's optional pre-unwind handler. In particular, a
1270 throw handler's handler procedure is invoked in the exact dynamic
1271 context of the @code{throw} expression, just as a pre-unwind handler is.
1272 @code{with-throw-handler} may be seen as a half-@code{catch}: it does
1273 everything that a @code{catch} would do until the point where
1274 @code{catch} would start unwinding the stack and dynamic context, but
1275 then it rethrows to the next innermost @code{catch} or throw handler
1278 Note also that since the dynamic context is not unwound, if a
1279 @code{with-throw-handler} handler throws to a key that does not match
1280 the @code{with-throw-handler} expression's @var{key}, the new throw may
1281 be handled by a @code{catch} or throw handler that is @emph{closer} to
1282 the throw than the first @code{with-throw-handler}.
1284 Here is an example to illustrate this behavior:
1289 (with-throw-handler 'b
1295 (lambda (key . args)
1301 This code will call @code{inner-handler} and then continue with the
1302 continuation of the inner @code{catch}.
1306 @subsubsection Throwing Exceptions
1308 The @code{throw} primitive is used to throw an exception. One argument,
1309 the @var{key}, is mandatory, and must be a symbol; it indicates the type
1310 of exception that is being thrown. Following the @var{key},
1311 @code{throw} accepts any number of additional arguments, whose meaning
1312 depends on the exception type. The documentation for each possible type
1313 of exception should specify the additional arguments that are expected
1314 for that kind of exception.
1316 @deffn {Scheme Procedure} throw key arg @dots{}
1317 @deffnx {C Function} scm_throw (key, args)
1318 Invoke the catch form matching @var{key}, passing @var{arg} @dots{} to
1321 @var{key} is a symbol. It will match catches of the same symbol or of
1324 If there is no handler at all, Guile prints an error and then exits.
1327 When an exception is thrown, it will be caught by the innermost
1328 @code{catch} or throw handler that applies to the type of the thrown
1329 exception; in other words, whose @var{key} is either @code{#t} or the
1330 same symbol as that used in the @code{throw} expression. Once Guile has
1331 identified the appropriate @code{catch} or throw handler, it handles the
1332 exception by applying the relevant handler procedure(s) to the arguments
1333 of the @code{throw}.
1335 If there is no appropriate @code{catch} or throw handler for a thrown
1336 exception, Guile prints an error to the current error port indicating an
1337 uncaught exception, and then exits. In practice, it is quite difficult
1338 to observe this behaviour, because Guile when used interactively
1339 installs a top level @code{catch} handler that will catch all exceptions
1340 and print an appropriate error message @emph{without} exiting. For
1341 example, this is what happens if you try to throw an unhandled exception
1342 in the standard Guile REPL; note that Guile's command loop continues
1343 after the error message:
1346 guile> (throw 'badex)
1347 <unnamed port>:3:1: In procedure gsubr-apply @dots{}
1348 <unnamed port>:3:1: unhandled-exception: badex
1353 The default uncaught exception behaviour can be observed by evaluating a
1354 @code{throw} expression from the shell command line:
1357 $ guile -c "(begin (throw 'badex) (display \"here\\n\"))"
1358 guile: uncaught throw to badex: ()
1363 That Guile exits immediately following the uncaught exception
1364 is shown by the absence of any output from the @code{display}
1365 expression, because Guile never gets to the point of evaluating that
1369 @node Exception Implementation
1370 @subsubsection How Guile Implements Exceptions
1372 It is traditional in Scheme to implement exception systems using
1373 @code{call-with-current-continuation}. Continuations
1374 (@pxref{Continuations}) are such a powerful concept that any other
1375 control mechanism --- including @code{catch} and @code{throw} --- can be
1376 implemented in terms of them.
1378 Guile does not implement @code{catch} and @code{throw} like this,
1379 though. Why not? Because Guile is specifically designed to be easy to
1380 integrate with applications written in C. In a mixed Scheme/C
1381 environment, the concept of @dfn{continuation} must logically include
1382 ``what happens next'' in the C parts of the application as well as the
1383 Scheme parts, and it turns out that the only reasonable way of
1384 implementing continuations like this is to save and restore the complete
1387 So Guile's implementation of @code{call-with-current-continuation} is a
1388 stack copying one. This allows it to interact well with ordinary C
1389 code, but means that creating and calling a continuation is slowed down
1390 by the time that it takes to copy the C stack.
1392 The more targeted mechanism provided by @code{catch} and @code{throw}
1393 does not need to save and restore the C stack because the @code{throw}
1394 always jumps to a location higher up the stack of the code that executes
1395 the @code{throw}. Therefore Guile implements the @code{catch} and
1396 @code{throw} primitives independently of
1397 @code{call-with-current-continuation}, in a way that takes advantage of
1398 this @emph{upwards only} nature of exceptions.
1401 @node Error Reporting
1402 @subsection Procedures for Signaling Errors
1404 Guile provides a set of convenience procedures for signaling error
1405 conditions that are implemented on top of the exception primitives just
1408 @deffn {Scheme Procedure} error msg arg @dots{}
1409 Raise an error with key @code{misc-error} and a message constructed by
1410 displaying @var{msg} and writing @var{arg} @enddots{}.
1413 @deffn {Scheme Procedure} scm-error key subr message args data
1414 @deffnx {C Function} scm_error_scm (key, subr, message, args, data)
1415 Raise an error with key @var{key}. @var{subr} can be a string
1416 naming the procedure associated with the error, or @code{#f}.
1417 @var{message} is the error message string, possibly containing
1418 @code{~S} and @code{~A} escapes. When an error is reported,
1419 these are replaced by formatting the corresponding members of
1420 @var{args}: @code{~A} (was @code{%s} in older versions of
1421 Guile) formats using @code{display} and @code{~S} (was
1422 @code{%S}) formats using @code{write}. @var{data} is a list or
1423 @code{#f} depending on @var{key}: if @var{key} is
1424 @code{system-error} then it should be a list containing the
1425 Unix @code{errno} value; If @var{key} is @code{signal} then it
1426 should be a list containing the Unix signal number; If
1427 @var{key} is @code{out-of-range}, @code{wrong-type-arg},
1428 or @code{keyword-argument-error},
1429 it is a list containing the bad value; otherwise
1430 it will usually be @code{#f}.
1433 @deffn {Scheme Procedure} strerror err
1434 @deffnx {C Function} scm_strerror (err)
1435 Return the Unix error message corresponding to @var{err}, an integer
1438 When @code{setlocale} has been called (@pxref{Locales}), the message
1439 is in the language and charset of @code{LC_MESSAGES}. (This is done
1443 @c begin (scm-doc-string "boot-9.scm" "false-if-exception")
1444 @deffn syntax false-if-exception expr
1445 Returns the result of evaluating its argument; however
1446 if an exception occurs then @code{#f} is returned instead.
1452 @subsection Dynamic Wind
1454 For Scheme code, the fundamental procedure to react to non-local entry
1455 and exits of dynamic contexts is @code{dynamic-wind}. C code could
1456 use @code{scm_internal_dynamic_wind}, but since C does not allow the
1457 convenient construction of anonymous procedures that close over
1458 lexical variables, this will be, well, inconvenient.
1460 Therefore, Guile offers the functions @code{scm_dynwind_begin} and
1461 @code{scm_dynwind_end} to delimit a dynamic extent. Within this
1462 dynamic extent, which is called a @dfn{dynwind context}, you can
1463 perform various @dfn{dynwind actions} that control what happens when
1464 the dynwind context is entered or left. For example, you can register
1465 a cleanup routine with @code{scm_dynwind_unwind_handler} that is
1466 executed when the context is left. There are several other more
1467 specialized dynwind actions as well, for example to temporarily block
1468 the execution of asyncs or to temporarily change the current output
1469 port. They are described elsewhere in this manual.
1471 Here is an example that shows how to prevent memory leaks.
1475 /* Suppose there is a function called FOO in some library that you
1476 would like to make available to Scheme code (or to C code that
1477 follows the Scheme conventions).
1479 FOO takes two C strings and returns a new string. When an error has
1480 occurred in FOO, it returns NULL.
1483 char *foo (char *s1, char *s2);
1485 /* SCM_FOO interfaces the C function FOO to the Scheme way of life.
1486 It takes care to free up all temporary strings in the case of
1491 scm_foo (SCM s1, SCM s2)
1493 char *c_s1, *c_s2, *c_res;
1495 scm_dynwind_begin (0);
1497 c_s1 = scm_to_locale_string (s1);
1499 /* Call 'free (c_s1)' when the dynwind context is left.
1501 scm_dynwind_unwind_handler (free, c_s1, SCM_F_WIND_EXPLICITLY);
1503 c_s2 = scm_to_locale_string (s2);
1505 /* Same as above, but more concisely.
1507 scm_dynwind_free (c_s2);
1509 c_res = foo (c_s1, c_s2);
1511 scm_memory_error ("foo");
1515 return scm_take_locale_string (res);
1519 @rnindex dynamic-wind
1520 @deffn {Scheme Procedure} dynamic-wind in_guard thunk out_guard
1521 @deffnx {C Function} scm_dynamic_wind (in_guard, thunk, out_guard)
1522 All three arguments must be 0-argument procedures.
1523 @var{in_guard} is called, then @var{thunk}, then
1526 If, any time during the execution of @var{thunk}, the
1527 dynamic extent of the @code{dynamic-wind} expression is escaped
1528 non-locally, @var{out_guard} is called. If the dynamic extent of
1529 the dynamic-wind is re-entered, @var{in_guard} is called. Thus
1530 @var{in_guard} and @var{out_guard} may be called any number of
1534 (define x 'normal-binding)
1537 (call-with-current-continuation
1543 (lambda () (set! x 'special-binding))
1547 (lambda () (display x) (newline)
1548 (call-with-current-continuation escape)
1549 (display x) (newline)
1554 (lambda () (set! x old-x)))))))
1560 @result{} normal-binding
1565 @result{} a-cont ;; the value of the (define a-cont...)
1567 @result{} normal-binding
1569 @result{} special-binding
1573 @deftp {C Type} scm_t_dynwind_flags
1574 This is an enumeration of several flags that modify the behavior of
1575 @code{scm_dynwind_begin}. The flags are listed in the following
1579 @item SCM_F_DYNWIND_REWINDABLE
1580 The dynamic context is @dfn{rewindable}. This means that it can be
1581 reentered non-locally (via the invocation of a continuation). The
1582 default is that a dynwind context can not be reentered non-locally.
1587 @deftypefn {C Function} void scm_dynwind_begin (scm_t_dynwind_flags flags)
1588 The function @code{scm_dynwind_begin} starts a new dynamic context and
1589 makes it the `current' one.
1591 The @var{flags} argument determines the default behavior of the
1592 context. Normally, use 0. This will result in a context that can not
1593 be reentered with a captured continuation. When you are prepared to
1594 handle reentries, include @code{SCM_F_DYNWIND_REWINDABLE} in
1597 Being prepared for reentry means that the effects of unwind handlers
1598 can be undone on reentry. In the example above, we want to prevent a
1599 memory leak on non-local exit and thus register an unwind handler that
1600 frees the memory. But once the memory is freed, we can not get it
1601 back on reentry. Thus reentry can not be allowed.
1603 The consequence is that continuations become less useful when
1604 non-reentrant contexts are captured, but you don't need to worry
1605 about that too much.
1607 The context is ended either implicitly when a non-local exit happens,
1608 or explicitly with @code{scm_dynwind_end}. You must make sure that a
1609 dynwind context is indeed ended properly. If you fail to call
1610 @code{scm_dynwind_end} for each @code{scm_dynwind_begin}, the behavior
1614 @deftypefn {C Function} void scm_dynwind_end ()
1615 End the current dynamic context explicitly and make the previous one
1619 @deftp {C Type} scm_t_wind_flags
1620 This is an enumeration of several flags that modify the behavior of
1621 @code{scm_dynwind_unwind_handler} and
1622 @code{scm_dynwind_rewind_handler}. The flags are listed in the
1626 @item SCM_F_WIND_EXPLICITLY
1627 @vindex SCM_F_WIND_EXPLICITLY
1628 The registered action is also carried out when the dynwind context is
1629 entered or left locally.
1633 @deftypefn {C Function} void scm_dynwind_unwind_handler (void (*func)(void *), void *data, scm_t_wind_flags flags)
1634 @deftypefnx {C Function} void scm_dynwind_unwind_handler_with_scm (void (*func)(SCM), SCM data, scm_t_wind_flags flags)
1635 Arranges for @var{func} to be called with @var{data} as its arguments
1636 when the current context ends implicitly. If @var{flags} contains
1637 @code{SCM_F_WIND_EXPLICITLY}, @var{func} is also called when the
1638 context ends explicitly with @code{scm_dynwind_end}.
1640 The function @code{scm_dynwind_unwind_handler_with_scm} takes care that
1641 @var{data} is protected from garbage collection.
1644 @deftypefn {C Function} void scm_dynwind_rewind_handler (void (*func)(void *), void *data, scm_t_wind_flags flags)
1645 @deftypefnx {C Function} void scm_dynwind_rewind_handler_with_scm (void (*func)(SCM), SCM data, scm_t_wind_flags flags)
1646 Arrange for @var{func} to be called with @var{data} as its argument when
1647 the current context is restarted by rewinding the stack. When @var{flags}
1648 contains @code{SCM_F_WIND_EXPLICITLY}, @var{func} is called immediately
1651 The function @code{scm_dynwind_rewind_handler_with_scm} takes care that
1652 @var{data} is protected from garbage collection.
1655 @deftypefn {C Function} void scm_dynwind_free (void *mem)
1656 Arrange for @var{mem} to be freed automatically whenever the current
1657 context is exited, whether normally or non-locally.
1658 @code{scm_dynwind_free (mem)} is an equivalent shorthand for
1659 @code{scm_dynwind_unwind_handler (free, mem, SCM_F_WIND_EXPLICITLY)}.
1663 @node Handling Errors
1664 @subsection How to Handle Errors
1666 Error handling is based on @code{catch} and @code{throw}. Errors are
1667 always thrown with a @var{key} and four arguments:
1671 @var{key}: a symbol which indicates the type of error. The symbols used
1672 by libguile are listed below.
1675 @var{subr}: the name of the procedure from which the error is thrown, or
1679 @var{message}: a string (possibly language and system dependent)
1680 describing the error. The tokens @code{~A} and @code{~S} can be
1681 embedded within the message: they will be replaced with members of the
1682 @var{args} list when the message is printed. @code{~A} indicates an
1683 argument printed using @code{display}, while @code{~S} indicates an
1684 argument printed using @code{write}. @var{message} can also be
1685 @code{#f}, to allow it to be derived from the @var{key} by the error
1686 handler (may be useful if the @var{key} is to be thrown from both C and
1690 @var{args}: a list of arguments to be used to expand @code{~A} and
1691 @code{~S} tokens in @var{message}. Can also be @code{#f} if no
1692 arguments are required.
1695 @var{rest}: a list of any additional objects required. e.g., when the
1696 key is @code{'system-error}, this contains the C errno value. Can also
1697 be @code{#f} if no additional objects are required.
1700 In addition to @code{catch} and @code{throw}, the following Scheme
1701 facilities are available:
1703 @deffn {Scheme Procedure} display-error frame port subr message args rest
1704 @deffnx {C Function} scm_display_error (frame, port, subr, message, args, rest)
1705 Display an error message to the output port @var{port}.
1706 @var{frame} is the frame in which the error occurred, @var{subr} is
1707 the name of the procedure in which the error occurred and
1708 @var{message} is the actual error message, which may contain
1709 formatting instructions. These will format the arguments in
1710 the list @var{args} accordingly. @var{rest} is currently
1714 The following are the error keys defined by libguile and the situations
1715 in which they are used:
1719 @cindex @code{error-signal}
1720 @code{error-signal}: thrown after receiving an unhandled fatal signal
1721 such as SIGSEGV, SIGBUS, SIGFPE etc. The @var{rest} argument in the throw
1722 contains the coded signal number (at present this is not the same as the
1723 usual Unix signal number).
1726 @cindex @code{system-error}
1727 @code{system-error}: thrown after the operating system indicates an
1728 error condition. The @var{rest} argument in the throw contains the
1732 @cindex @code{numerical-overflow}
1733 @code{numerical-overflow}: numerical overflow.
1736 @cindex @code{out-of-range}
1737 @code{out-of-range}: the arguments to a procedure do not fall within the
1741 @cindex @code{wrong-type-arg}
1742 @code{wrong-type-arg}: an argument to a procedure has the wrong type.
1745 @cindex @code{wrong-number-of-args}
1746 @code{wrong-number-of-args}: a procedure was called with the wrong number
1750 @cindex @code{memory-allocation-error}
1751 @code{memory-allocation-error}: memory allocation error.
1754 @cindex @code{stack-overflow}
1755 @code{stack-overflow}: stack overflow error.
1758 @cindex @code{regular-expression-syntax}
1759 @code{regular-expression-syntax}: errors generated by the regular
1763 @cindex @code{misc-error}
1764 @code{misc-error}: other errors.
1768 @subsubsection C Support
1770 In the following C functions, @var{SUBR} and @var{MESSAGE} parameters
1771 can be @code{NULL} to give the effect of @code{#f} described above.
1773 @deftypefn {C Function} SCM scm_error (SCM @var{key}, char *@var{subr}, char *@var{message}, SCM @var{args}, SCM @var{rest})
1774 Throw an error, as per @code{scm-error} (@pxref{Error Reporting}).
1777 @deftypefn {C Function} void scm_syserror (char *@var{subr})
1778 @deftypefnx {C Function} void scm_syserror_msg (char *@var{subr}, char *@var{message}, SCM @var{args})
1779 Throw an error with key @code{system-error} and supply @code{errno} in
1780 the @var{rest} argument. For @code{scm_syserror} the message is
1781 generated using @code{strerror}.
1783 Care should be taken that any code in between the failing operation
1784 and the call to these routines doesn't change @code{errno}.
1787 @deftypefn {C Function} void scm_num_overflow (char *@var{subr})
1788 @deftypefnx {C Function} void scm_out_of_range (char *@var{subr}, SCM @var{bad_value})
1789 @deftypefnx {C Function} void scm_wrong_num_args (SCM @var{proc})
1790 @deftypefnx {C Function} void scm_wrong_type_arg (char *@var{subr}, int @var{argnum}, SCM @var{bad_value})
1791 @deftypefnx {C Function} void scm_wrong_type_arg_msg (char *@var{subr}, int @var{argnum}, SCM @var{bad_value}, const char *@var{expected})
1792 @deftypefnx {C Function} void scm_memory_error (char *@var{subr})
1793 @deftypefnx {C Function} void scm_misc_error (const char *@var{subr}, const char *@var{message}, SCM @var{args})
1794 Throw an error with the various keys described above.
1796 In @code{scm_wrong_num_args}, @var{proc} should be a Scheme symbol
1797 which is the name of the procedure incorrectly invoked. The other
1798 routines take the name of the invoked procedure as a C string.
1800 In @code{scm_wrong_type_arg_msg}, @var{expected} is a C string
1801 describing the type of argument that was expected.
1803 In @code{scm_misc_error}, @var{message} is the error message string,
1804 possibly containing @code{simple-format} escapes (@pxref{Writing}), and
1805 the corresponding arguments in the @var{args} list.
1809 @subsubsection Signalling Type Errors
1811 Every function visible at the Scheme level should aggressively check the
1812 types of its arguments, to avoid misinterpreting a value, and perhaps
1813 causing a segmentation fault. Guile provides some macros to make this
1816 @deftypefn Macro void SCM_ASSERT (int @var{test}, SCM @var{obj}, unsigned int @var{position}, const char *@var{subr})
1817 @deftypefnx Macro void SCM_ASSERT_TYPE (int @var{test}, SCM @var{obj}, unsigned int @var{position}, const char *@var{subr}, const char *@var{expected})
1818 If @var{test} is zero, signal a ``wrong type argument'' error,
1819 attributed to the subroutine named @var{subr}, operating on the value
1820 @var{obj}, which is the @var{position}'th argument of @var{subr}.
1822 In @code{SCM_ASSERT_TYPE}, @var{expected} is a C string describing the
1823 type of argument that was expected.
1826 @deftypefn Macro int SCM_ARG1
1827 @deftypefnx Macro int SCM_ARG2
1828 @deftypefnx Macro int SCM_ARG3
1829 @deftypefnx Macro int SCM_ARG4
1830 @deftypefnx Macro int SCM_ARG5
1831 @deftypefnx Macro int SCM_ARG6
1832 @deftypefnx Macro int SCM_ARG7
1833 One of the above values can be used for @var{position} to indicate the
1834 number of the argument of @var{subr} which is being checked.
1835 Alternatively, a positive integer number can be used, which allows to
1836 check arguments after the seventh. However, for parameter numbers up to
1837 seven it is preferable to use @code{SCM_ARGN} instead of the
1838 corresponding raw number, since it will make the code easier to
1842 @deftypefn Macro int SCM_ARGn
1843 Passing a value of zero or @code{SCM_ARGn} for @var{position} allows to
1844 leave it unspecified which argument's type is incorrect. Again,
1845 @code{SCM_ARGn} should be preferred over a raw zero constant.
1848 @node Continuation Barriers
1849 @subsection Continuation Barriers
1851 The non-local flow of control caused by continuations might sometimes
1852 not be wanted. You can use @code{with-continuation-barrier} to erect
1853 fences that continuations can not pass.
1855 @deffn {Scheme Procedure} with-continuation-barrier proc
1856 @deffnx {C Function} scm_with_continuation_barrier (proc)
1857 Call @var{proc} and return its result. Do not allow the invocation of
1858 continuations that would leave or enter the dynamic extent of the call
1859 to @code{with-continuation-barrier}. Such an attempt causes an error
1862 Throws (such as errors) that are not caught from within @var{proc} are
1863 caught by @code{with-continuation-barrier}. In that case, a short
1864 message is printed to the current error port and @code{#f} is returned.
1866 Thus, @code{with-continuation-barrier} returns exactly once.
1869 @deftypefn {C Function} {void *} scm_c_with_continuation_barrier (void *(*func) (void *), void *data)
1870 Like @code{scm_with_continuation_barrier} but call @var{func} on
1871 @var{data}. When an error is caught, @code{NULL} is returned.
1876 @c TeX-master: "guile.texi"