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 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:: Evaluating a sequence of expressions.
15 * if cond case:: Simple conditional evaluation.
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 Evaluating a Sequence of Expressions
33 @cindex expression sequencing
35 The @code{begin} syntax is used for grouping several expressions
36 together so that they are treated as if they were one expression.
37 This is particularly important when syntactic expressions are used
38 which only allow one expression, but the programmer wants to use more
39 than one expression in that place. As an example, consider the
40 conditional expression below:
44 (begin (display "greater") (newline)))
47 If the two calls to @code{display} and @code{newline} were not embedded
48 in a @code{begin}-statement, the call to @code{newline} would get
49 misinterpreted as the else-branch of the @code{if}-expression.
51 @deffn syntax begin expr1 expr2 @dots{}
52 The expression(s) are evaluated in left-to-right order and the value
53 of the last expression is returned as the value of the
54 @code{begin}-expression. This expression type is used when the
55 expressions before the last one are evaluated for their side effects.
57 Guile also allows the expression @code{(begin)}, a @code{begin} with no
58 sub-expressions. Such an expression returns the `unspecified' value.
62 @subsection Simple Conditional Evaluation
64 @cindex conditional evaluation
69 Guile provides three syntactic constructs for conditional evaluation.
70 @code{if} is the normal if-then-else expression (with an optional else
71 branch), @code{cond} is a conditional expression with multiple branches
72 and @code{case} branches if an expression has one of a set of constant
75 @deffn syntax if test consequent [alternate]
76 All arguments may be arbitrary expressions. First, @var{test} is
77 evaluated. If it returns a true value, the expression @var{consequent}
78 is evaluated and @var{alternate} is ignored. If @var{test} evaluates to
79 @code{#f}, @var{alternate} is evaluated instead. The value of the
80 evaluated branch (@var{consequent} or @var{alternate}) is returned as
81 the value of the @code{if} expression.
83 When @var{alternate} is omitted and the @var{test} evaluates to
84 @code{#f}, the value of the expression is not specified.
87 @deffn syntax cond clause1 clause2 @dots{}
88 Each @code{cond}-clause must look like this:
91 (@var{test} @var{expression} @dots{})
94 where @var{test} and @var{expression} are arbitrary expression, or like
98 (@var{test} => @var{expression})
101 where @var{expression} must evaluate to a procedure.
103 The @var{test}s of the clauses are evaluated in order and as soon as one
104 of them evaluates to a true values, the corresponding @var{expression}s
105 are evaluated in order and the last value is returned as the value of
106 the @code{cond}-expression. For the @code{=>} clause type,
107 @var{expression} is evaluated and the resulting procedure is applied to
108 the value of @var{test}. The result of this procedure application is
109 then the result of the @code{cond}-expression.
112 @cindex general cond clause
113 @cindex multiple values and cond
114 One additional @code{cond}-clause is available as an extension to
118 (@var{test} @var{guard} => @var{expression})
121 where @var{guard} and @var{expression} must evaluate to procedures.
122 For this clause type, @var{test} may return multiple values, and
123 @code{cond} ignores its boolean state; instead, @code{cond} evaluates
124 @var{guard} and applies the resulting procedure to the value(s) of
125 @var{test}, as if @var{guard} were the @var{consumer} argument of
126 @code{call-with-values}. Iff the result of that procedure call is a
127 true value, it evaluates @var{expression} and applies the resulting
128 procedure to the value(s) of @var{test}, in the same manner as the
129 @var{guard} was called.
131 The @var{test} of the last @var{clause} may be the symbol @code{else}.
132 Then, if none of the preceding @var{test}s is true, the
133 @var{expression}s following the @code{else} are evaluated to produce the
134 result of the @code{cond}-expression.
137 @deffn syntax case key clause1 clause2 @dots{}
138 @var{key} may be any expression, the @var{clause}s must have the form
141 ((@var{datum1} @dots{}) @var{expr1} @var{expr2} @dots{})
144 and the last @var{clause} may have the form
147 (else @var{expr1} @var{expr2} @dots{})
150 All @var{datum}s must be distinct. First, @var{key} is evaluated. The
151 the result of this evaluation is compared against all @var{datum}s using
152 @code{eqv?}. When this comparison succeeds, the expression(s) following
153 the @var{datum} are evaluated from left to right, returning the value of
154 the last expression as the result of the @code{case} expression.
156 If the @var{key} matches no @var{datum} and there is an
157 @code{else}-clause, the expressions following the @code{else} are
158 evaluated. If there is no such clause, the result of the expression is
164 @subsection Conditional Evaluation of a Sequence of Expressions
166 @code{and} and @code{or} evaluate all their arguments in order, similar
167 to @code{begin}, but evaluation stops as soon as one of the expressions
168 evaluates to false or true, respectively.
170 @deffn syntax and expr @dots{}
171 Evaluate the @var{expr}s from left to right and stop evaluation as soon
172 as one expression evaluates to @code{#f}; the remaining expressions are
173 not evaluated. The value of the last evaluated expression is returned.
174 If no expression evaluates to @code{#f}, the value of the last
175 expression is returned.
177 If used without expressions, @code{#t} is returned.
180 @deffn syntax or expr @dots{}
181 Evaluate the @var{expr}s from left to right and stop evaluation as soon
182 as one expression evaluates to a true value (that is, a value different
183 from @code{#f}); the remaining expressions are not evaluated. The value
184 of the last evaluated expression is returned. If all expressions
185 evaluate to @code{#f}, @code{#f} is returned.
187 If used without expressions, @code{#f} is returned.
192 @subsection Iteration mechanisms
198 Scheme has only few iteration mechanisms, mainly because iteration in
199 Scheme programs is normally expressed using recursion. Nevertheless,
200 R5RS defines a construct for programming loops, calling @code{do}. In
201 addition, Guile has an explicit looping syntax called @code{while}.
203 @deffn syntax do ((variable init [step]) @dots{}) (test [expr @dots{}]) body @dots{}
204 Bind @var{variable}s and evaluate @var{body} until @var{test} is true.
205 The return value is the last @var{expr} after @var{test}, if given. A
206 simple example will illustrate the basic form,
216 Or with two variables and a final return value,
223 (format #t "3**~s is ~s\n" i p))
233 The @var{variable} bindings are established like a @code{let}, in that
234 the expressions are all evaluated and then all bindings made. When
235 iterating, the optional @var{step} expressions are evaluated with the
236 previous bindings in scope, then new bindings all made.
238 The @var{test} expression is a termination condition. Looping stops
239 when the @var{test} is true. It's evaluated before running the
240 @var{body} each time, so if it's true the first time then @var{body}
243 The optional @var{expr}s after the @var{test} are evaluated at the end
244 of looping, with the final @var{variable} bindings available. The
245 last @var{expr} gives the return value, or if there are no @var{expr}s
246 the return value is unspecified.
248 Each iteration establishes bindings to fresh locations for the
249 @var{variable}s, like a new @code{let} for each iteration. This is
250 done for @var{variable}s without @var{step} expressions too. The
251 following illustrates this, showing how a new @code{i} is captured by
252 the @code{lambda} in each iteration (@pxref{About Closure,, The
253 Concept of Closure}).
259 (set! lst (cons (lambda () i) lst)))
260 (map (lambda (proc) (proc)) lst)
266 @deffn syntax while cond body @dots{}
267 Run a loop executing the @var{body} forms while @var{cond} is true.
268 @var{cond} is tested at the start of each iteration, so if it's
269 @code{#f} the first time then @var{body} is not executed at all. The
270 return value is unspecified.
272 Within @code{while}, two extra bindings are provided, they can be used
273 from both @var{cond} and @var{body}.
275 @deffn {Scheme Procedure} break
276 Break out of the @code{while} form.
279 @deffn {Scheme Procedure} continue
280 Abandon the current iteration, go back to the start and test
281 @var{cond} again, etc.
284 Each @code{while} form gets its own @code{break} and @code{continue}
285 procedures, operating on that @code{while}. This means when loops are
286 nested the outer @code{break} can be used to escape all the way out.
291 (let ((outer-break break))
298 Note that each @code{break} and @code{continue} procedure can only be
299 used within the dynamic extent of its @code{while}. Outside the
300 @code{while} their behaviour is unspecified.
304 Another very common way of expressing iteration in Scheme programs is
305 the use of the so-called @dfn{named let}.
307 Named let is a variant of @code{let} which creates a procedure and calls
308 it in one step. Because of the newly created procedure, named let is
309 more powerful than @code{do}--it can be used for iteration, but also
310 for arbitrary recursion.
312 @deffn syntax let variable bindings body
313 For the definition of @var{bindings} see the documentation about
314 @code{let} (@pxref{Local Bindings}).
316 Named @code{let} works as follows:
320 A new procedure which accepts as many arguments as are in @var{bindings}
321 is created and bound locally (using @code{let}) to @var{variable}. The
322 new procedure's formal argument names are the name of the
326 The @var{body} expressions are inserted into the newly created procedure.
329 The procedure is called with the @var{init} expressions as the formal
333 The next example implements a loop which iterates (by recursion) 1000
350 @cindex delimited continuations
351 @cindex composable continuations
352 @cindex non-local exit
354 Prompts are control-flow barriers between different parts of a program. In the
355 same way that a user sees a shell prompt (e.g., the Bash prompt) as a barrier
356 between the operating system and her programs, Scheme prompts allow the Scheme
357 programmer to treat parts of programs as if they were running in different
360 We use this roundabout explanation because, unless you're a functional
361 programming junkie, you probably haven't heard the term, ``delimited, composable
362 continuation''. That's OK; it's a relatively recent topic, but a very useful
365 @deffn {Scheme Procedure} call-with-prompt tag thunk handler
366 Set up a prompt, and call @var{thunk} within that prompt.
368 During the dynamic extent of the call to @var{thunk}, a prompt named @var{tag}
369 will be present in the dynamic context, such that if a user calls
370 @code{abort-to-prompt} (see below) with that tag, control rewinds back to the
371 prompt, and the @var{handler} is run.
373 @var{handler} must be a procedure. The first argument to @var{handler} will be
374 the state of the computation begun when @var{thunk} was called, and ending with
375 the call to @code{abort-to-prompt}. The remaining arguments to @var{handler} are
376 those passed to @code{abort-to-prompt}.
379 @deffn {Scheme Procedure} abort-to-prompt tag val ...
380 Unwind the dynamic and control context to the nearest prompt named @var{tag},
381 also passing the given values.
384 C programmers may recognize @code{call-with-prompt} and @code{abort-to-prompt}
385 as a fancy kind of @code{setjmp} and @code{longjmp}, respectively. Prompts are
386 indeed quite useful as non-local escape mechanisms. Guile's @code{catch} and
387 @code{throw} are implemented in terms of prompts. Prompts are more convenient
388 than @code{longjmp}, in that one has the opportunity to pass multiple values to
391 Also unlike @code{longjmp}, the prompt handler is given the full state of the
392 process that was aborted, as the first argument to the prompt's handler. That
393 state is the @dfn{continuation} of the computation wrapped by the prompt. It is
394 a @dfn{delimited continuation}, because it is not the whole continuation of the
395 program; rather, just the computation initiated by the call to
396 @code{call-with-prompt}.
398 The continuation is a procedure, and may be reinstated simply by invoking it,
399 with any number of values. Here's where things get interesting, and complicated
400 as well. Besides being described as delimited, continuations reified by prompts
401 are also @dfn{composable}, because invoking a prompt-saved continuation composes
402 that continuation with the current one.
404 Imagine you have saved a continuation via call-with-prompt:
413 (+ 34 (abort-to-prompt 'foo)))
418 The resulting continuation is the addition of 34. It's as if you had written:
426 So, if we call @code{cont} with one numeric value, we get that number,
436 The last example illustrates what we mean when we say, "composes with the
437 current continuation". We mean that there is a current continuation -- some
438 remaining things to compute, like @code{(lambda (x) (* x 2))} -- and that
439 calling the saved continuation doesn't wipe out the current continuation, it
440 composes the saved continuation with the current one.
442 We're belaboring the point here because traditional Scheme continuations, as
443 discussed in the next section, aren't composable, and are actually less
444 expressive than continuations captured by prompts. But there's a place for them
447 Before moving on, we should mention that if the handler of a prompt is a
448 @code{lambda} expression, and the first argument isn't referenced, an abort to
449 that prompt will not cause a continuation to be reified. This can be an
450 important efficiency consideration to keep in mind.
454 @subsection Continuations
455 @cindex continuations
457 A ``continuation'' is the code that will execute when a given function
458 or expression returns. For example, consider
463 (display (bar)) (newline)
467 The continuation from the call to @code{bar} comprises a
468 @code{display} of the value returned, a @code{newline} and an
469 @code{exit}. This can be expressed as a function of one argument.
473 (display r) (newline)
477 In Scheme, continuations are represented as special procedures just
478 like this. The special property is that when a continuation is called
479 it abandons the current program location and jumps directly to that
480 represented by the continuation.
482 A continuation is like a dynamic label, capturing at run-time a point
483 in program execution, including all the nested calls that have lead to
484 it (or rather the code that will execute when those calls return).
486 Continuations are created with the following functions.
488 @deffn {Scheme Procedure} call-with-current-continuation proc
489 @deffnx {Scheme Procedure} call/cc proc
490 @rnindex call-with-current-continuation
491 Capture the current continuation and call @code{(@var{proc}
492 @var{cont})} with it. The return value is the value returned by
493 @var{proc}, or when @code{(@var{cont} @var{value})} is later invoked,
494 the return is the @var{value} passed.
496 Normally @var{cont} should be called with one argument, but when the
497 location resumed is expecting multiple values (@pxref{Multiple
498 Values}) then they should be passed as multiple arguments, for
499 instance @code{(@var{cont} @var{x} @var{y} @var{z})}.
501 @var{cont} may only be used from the same side of a continuation
502 barrier as it was created (@pxref{Continuation Barriers}), and in a
503 multi-threaded program only from the thread in which it was created.
505 The call to @var{proc} is not part of the continuation captured, it runs
506 only when the continuation is created. Often a program will want to
507 store @var{cont} somewhere for later use; this can be done in
510 The @code{call} in the name @code{call-with-current-continuation}
511 refers to the way a call to @var{proc} gives the newly created
512 continuation. It's not related to the way a call is used later to
513 invoke that continuation.
515 @code{call/cc} is an alias for @code{call-with-current-continuation}.
516 This is in common use since the latter is rather long.
521 Here is a simple example,
525 (format #t "the return is ~a\n"
529 @result{} the return is 1
532 @result{} the return is 2
535 @code{call/cc} captures a continuation in which the value returned is
536 going to be displayed by @code{format}. The @code{lambda} stores this
537 in @code{kont} and gives an initial return @code{1} which is
538 displayed. The later invocation of @code{kont} resumes the captured
539 point, but this time returning @code{2}, which is displayed.
541 When Guile is run interactively, a call to @code{format} like this has
542 an implicit return back to the read-eval-print loop. @code{call/cc}
543 captures that like any other return, which is why interactively
544 @code{kont} will come back to read more input.
547 C programmers may note that @code{call/cc} is like @code{setjmp} in
548 the way it records at runtime a point in program execution. A call to
549 a continuation is like a @code{longjmp} in that it abandons the
550 present location and goes to the recorded one. Like @code{longjmp},
551 the value passed to the continuation is the value returned by
552 @code{call/cc} on resuming there. However @code{longjmp} can only go
553 up the program stack, but the continuation mechanism can go anywhere.
555 When a continuation is invoked, @code{call/cc} and subsequent code
556 effectively ``returns'' a second time. It can be confusing to imagine
557 a function returning more times than it was called. It may help
558 instead to think of it being stealthily re-entered and then program
559 flow going on as normal.
561 @code{dynamic-wind} (@pxref{Dynamic Wind}) can be used to ensure setup
562 and cleanup code is run when a program locus is resumed or abandoned
563 through the continuation mechanism.
566 Continuations are a powerful mechanism, and can be used to implement
567 almost any sort of control structure, such as loops, coroutines, or
570 However the implementation of continuations in Guile is not as
571 efficient as one might hope, because Guile is designed to cooperate
572 with programs written in other languages, such as C, which do not know
573 about continuations. Basically continuations are captured by a block
574 copy of the stack, and resumed by copying back.
576 For this reason, continuations captured by @code{call/cc} should be used only
577 when there is no other simple way to achieve the desired result, or when the
578 elegance of the continuation mechanism outweighs the need for performance.
580 Escapes upwards from loops or nested functions are generally best
581 handled with prompts (@pxref{Prompts}). Coroutines can be
582 efficiently implemented with cooperating threads (a thread holds a
583 full program stack but doesn't copy it around the way continuations
587 @node Multiple Values
588 @subsection Returning and Accepting Multiple Values
590 @cindex multiple values
593 Scheme allows a procedure to return more than one value to its caller.
594 This is quite different to other languages which only allow
595 single-value returns. Returning multiple values is different from
596 returning a list (or pair or vector) of values to the caller, because
597 conceptually not @emph{one} compound object is returned, but several
600 The primitive procedures for handling multiple values are @code{values}
601 and @code{call-with-values}. @code{values} is used for returning
602 multiple values from a procedure. This is done by placing a call to
603 @code{values} with zero or more arguments in tail position in a
604 procedure body. @code{call-with-values} combines a procedure returning
605 multiple values with a procedure which accepts these values as
609 @deffn {Scheme Procedure} values arg1 @dots{} argN
610 @deffnx {C Function} scm_values (args)
611 Delivers all of its arguments to its continuation. Except for
612 continuations created by the @code{call-with-values} procedure,
613 all continuations take exactly one value. The effect of
614 passing no value or more than one value to continuations that
615 were not created by @code{call-with-values} is unspecified.
617 For @code{scm_values}, @var{args} is a list of arguments and the
618 return is a multiple-values object which the caller can return. In
619 the current implementation that object shares structure with
620 @var{args}, so @var{args} should not be modified subsequently.
623 @rnindex call-with-values
624 @deffn {Scheme Procedure} call-with-values producer consumer
625 Calls its @var{producer} argument with no values and a
626 continuation that, when passed some values, calls the
627 @var{consumer} procedure with those values as arguments. The
628 continuation for the call to @var{consumer} is the continuation
629 of the call to @code{call-with-values}.
632 (call-with-values (lambda () (values 4 5))
638 (call-with-values * -)
643 In addition to the fundamental procedures described above, Guile has a
644 module which exports a syntax called @code{receive}, which is much
645 more convenient. This is in the @code{(ice-9 receive)} and is the
646 same as specified by SRFI-8 (@pxref{SRFI-8}).
649 (use-modules (ice-9 receive))
652 @deffn {library syntax} receive formals expr body @dots{}
653 Evaluate the expression @var{expr}, and bind the result values (zero
654 or more) to the formal arguments in @var{formals}. @var{formals} is a
655 list of symbols, like the argument list in a @code{lambda}
656 (@pxref{Lambda}). After binding the variables, the expressions in
657 @var{body} @dots{} are evaluated in order, the return value is the
658 result from the last expression.
660 For example getting results from @code{partition} in SRFI-1
664 (receive (odds evens)
665 (partition odd? '(7 4 2 8 3))
669 @print{} (7 3) and (4 2 8)
676 @subsection Exceptions
677 @cindex error handling
678 @cindex exception handling
680 A common requirement in applications is to want to jump
681 @dfn{non-locally} from the depths of a computation back to, say, the
682 application's main processing loop. Usually, the place that is the
683 target of the jump is somewhere in the calling stack of procedures that
684 called the procedure that wants to jump back. For example, typical
685 logic for a key press driven application might look something like this:
689 read the next key press and call dispatch-key
692 lookup the key in a keymap and call an appropriate procedure,
696 interactively read the required file name, then call
700 check whether file exists; if not, jump back to main-loop
704 The jump back to @code{main-loop} could be achieved by returning through
705 the stack one procedure at a time, using the return value of each
706 procedure to indicate the error condition, but Guile (like most modern
707 programming languages) provides an additional mechanism called
708 @dfn{exception handling} that can be used to implement such jumps much
712 * Exception Terminology:: Different ways to say the same thing.
713 * Catch:: Setting up to catch exceptions.
714 * Throw Handlers:: Handling exceptions before unwinding the stack.
715 * Throw:: Throwing an exception.
716 * Exception Implementation:: How Guile implements exceptions.
720 @node Exception Terminology
721 @subsubsection Exception Terminology
723 There are several variations on the terminology for dealing with
724 non-local jumps. It is useful to be aware of them, and to realize
725 that they all refer to the same basic mechanism.
729 Actually making a non-local jump may be called @dfn{raising an
730 exception}, @dfn{raising a signal}, @dfn{throwing an exception} or
731 @dfn{doing a long jump}. When the jump indicates an error condition,
732 people may talk about @dfn{signalling}, @dfn{raising} or @dfn{throwing}
736 Handling the jump at its target may be referred to as @dfn{catching} or
737 @dfn{handling} the @dfn{exception}, @dfn{signal} or, where an error
738 condition is involved, @dfn{error}.
741 Where @dfn{signal} and @dfn{signalling} are used, special care is needed
742 to avoid the risk of confusion with POSIX signals.
744 This manual prefers to speak of throwing and catching exceptions, since
745 this terminology matches the corresponding Guile primitives.
749 @subsubsection Catching Exceptions
751 @code{catch} is used to set up a target for a possible non-local jump.
752 The arguments of a @code{catch} expression are a @dfn{key}, which
753 restricts the set of exceptions to which this @code{catch} applies, a
754 thunk that specifies the code to execute and one or two @dfn{handler}
755 procedures that say what to do if an exception is thrown while executing
756 the code. If the execution thunk executes @dfn{normally}, which means
757 without throwing any exceptions, the handler procedures are not called
760 When an exception is thrown using the @code{throw} function, the first
761 argument of the @code{throw} is a symbol that indicates the type of the
762 exception. For example, Guile throws an exception using the symbol
763 @code{numerical-overflow} to indicate numerical overflow errors such as
769 ABORT: (numerical-overflow)
772 The @var{key} argument in a @code{catch} expression corresponds to this
773 symbol. @var{key} may be a specific symbol, such as
774 @code{numerical-overflow}, in which case the @code{catch} applies
775 specifically to exceptions of that type; or it may be @code{#t}, which
776 means that the @code{catch} applies to all exceptions, irrespective of
779 The second argument of a @code{catch} expression should be a thunk
780 (i.e. a procedure that accepts no arguments) that specifies the normal
781 case code. The @code{catch} is active for the execution of this thunk,
782 including any code called directly or indirectly by the thunk's body.
783 Evaluation of the @code{catch} expression activates the catch and then
786 The third argument of a @code{catch} expression is a handler procedure.
787 If an exception is thrown, this procedure is called with exactly the
788 arguments specified by the @code{throw}. Therefore, the handler
789 procedure must be designed to accept a number of arguments that
790 corresponds to the number of arguments in all @code{throw} expressions
791 that can be caught by this @code{catch}.
793 The fourth, optional argument of a @code{catch} expression is another
794 handler procedure, called the @dfn{pre-unwind} handler. It differs from
795 the third argument in that if an exception is thrown, it is called,
796 @emph{before} the third argument handler, in exactly the dynamic context
797 of the @code{throw} expression that threw the exception. This means
798 that it is useful for capturing or displaying the stack at the point of
799 the @code{throw}, or for examining other aspects of the dynamic context,
800 such as fluid values, before the context is unwound back to that of the
801 prevailing @code{catch}.
803 @deffn {Scheme Procedure} catch key thunk handler [pre-unwind-handler]
804 @deffnx {C Function} scm_catch_with_pre_unwind_handler (key, thunk, handler, pre_unwind_handler)
805 @deffnx {C Function} scm_catch (key, thunk, handler)
806 Invoke @var{thunk} in the dynamic context of @var{handler} for
807 exceptions matching @var{key}. If thunk throws to the symbol
808 @var{key}, then @var{handler} is invoked this way:
810 (handler key args ...)
813 @var{key} is a symbol or @code{#t}.
815 @var{thunk} takes no arguments. If @var{thunk} returns
816 normally, that is the return value of @code{catch}.
818 Handler is invoked outside the scope of its own @code{catch}.
819 If @var{handler} again throws to the same key, a new handler
820 from further up the call chain is invoked.
822 If the key is @code{#t}, then a throw to @emph{any} symbol will
823 match this call to @code{catch}.
825 If a @var{pre-unwind-handler} is given and @var{thunk} throws
826 an exception that matches @var{key}, Guile calls the
827 @var{pre-unwind-handler} before unwinding the dynamic state and
828 invoking the main @var{handler}. @var{pre-unwind-handler} should
829 be a procedure with the same signature as @var{handler}, that
830 is @code{(lambda (key . args))}. It is typically used to save
831 the stack at the point where the exception occurred, but can also
832 query other parts of the dynamic state at that point, such as
835 A @var{pre-unwind-handler} can exit either normally or non-locally.
836 If it exits normally, Guile unwinds the stack and dynamic context
837 and then calls the normal (third argument) handler. If it exits
838 non-locally, that exit determines the continuation.
841 If a handler procedure needs to match a variety of @code{throw}
842 expressions with varying numbers of arguments, you should write it like
851 The @var{key} argument is guaranteed always to be present, because a
852 @code{throw} without a @var{key} is not valid. The number and
853 interpretation of the @var{args} varies from one type of exception to
854 another, but should be specified by the documentation for each exception
857 Note that, once the normal (post-unwind) handler procedure is invoked,
858 the catch that led to the handler procedure being called is no longer
859 active. Therefore, if the handler procedure itself throws an exception,
860 that exception can only be caught by another active catch higher up the
861 call stack, if there is one.
864 @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)
865 @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)
866 The above @code{scm_catch_with_pre_unwind_handler} and @code{scm_catch}
867 take Scheme procedures as body and handler arguments.
868 @code{scm_c_catch} and @code{scm_internal_catch} are equivalents taking
871 @var{body} is called as @code{@var{body} (@var{body_data})} with a catch
872 on exceptions of the given @var{tag} type. If an exception is caught,
873 @var{pre_unwind_handler} and @var{handler} are called as
874 @code{@var{handler} (@var{handler_data}, @var{key}, @var{args})}.
875 @var{key} and @var{args} are the @code{SCM} key and argument list from
878 @tpindex scm_t_catch_body
879 @tpindex scm_t_catch_handler
880 @var{body} and @var{handler} should have the following prototypes.
881 @code{scm_t_catch_body} and @code{scm_t_catch_handler} are pointer
885 SCM body (void *data);
886 SCM handler (void *data, SCM key, SCM args);
889 The @var{body_data} and @var{handler_data} parameters are passed to
890 the respective calls so an application can communicate extra
891 information to those functions.
893 If the data consists of an @code{SCM} object, care should be taken
894 that it isn't garbage collected while still required. If the
895 @code{SCM} is a local C variable, one way to protect it is to pass a
896 pointer to that variable as the data parameter, since the C compiler
897 will then know the value must be held on the stack. Another way is to
898 use @code{scm_remember_upto_here_1} (@pxref{Remembering During
904 @subsubsection Throw Handlers
906 It's sometimes useful to be able to intercept an exception that is being
907 thrown before the stack is unwound. This could be to clean up some
908 related state, to print a backtrace, or to pass information about the
909 exception to a debugger, for example. The @code{with-throw-handler}
910 procedure provides a way to do this.
912 @deffn {Scheme Procedure} with-throw-handler key thunk handler
913 @deffnx {C Function} scm_with_throw_handler (key, thunk, handler)
914 Add @var{handler} to the dynamic context as a throw handler
915 for key @var{key}, then invoke @var{thunk}.
917 This behaves exactly like @code{catch}, except that it does not unwind
918 the stack before invoking @var{handler}. If the @var{handler} procedure
919 returns normally, Guile rethrows the same exception again to the next
920 innermost catch or throw handler. @var{handler} may exit nonlocally, of
921 course, via an explicit throw or via invoking a continuation.
924 Typically @var{handler} is used to display a backtrace of the stack at
925 the point where the corresponding @code{throw} occurred, or to save off
926 this information for possible display later.
928 Not unwinding the stack means that throwing an exception that is handled
929 via a throw handler is equivalent to calling the throw handler handler
930 inline instead of each @code{throw}, and then omitting the surrounding
931 @code{with-throw-handler}. In other words,
934 (with-throw-handler 'key
935 (lambda () @dots{} (throw 'key args @dots{}) @dots{})
940 is mostly equivalent to
943 ((lambda () @dots{} (handler 'key args @dots{}) @dots{}))
946 In particular, the dynamic context when @var{handler} is invoked is that
947 of the site where @code{throw} is called. The examples are not quite
948 equivalent, because the body of a @code{with-throw-handler} is not in
949 tail position with respect to the @code{with-throw-handler}, and if
950 @var{handler} exits normally, Guile arranges to rethrow the error, but
951 hopefully the intention is clear. (For an introduction to what is meant
952 by dynamic context, @xref{Dynamic Wind}.)
954 @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)
955 The above @code{scm_with_throw_handler} takes Scheme procedures as body
956 (thunk) and handler arguments. @code{scm_c_with_throw_handler} is an
957 equivalent taking C functions. See @code{scm_c_catch} (@pxref{Catch})
958 for a description of the parameters, the behaviour however of course
959 follows @code{with-throw-handler}.
962 If @var{thunk} throws an exception, Guile handles that exception by
963 invoking the innermost @code{catch} or throw handler whose key matches
964 that of the exception. When the innermost thing is a throw handler,
965 Guile calls the specified handler procedure using @code{(apply
966 @var{handler} key args)}. The handler procedure may either return
967 normally or exit non-locally. If it returns normally, Guile passes the
968 exception on to the next innermost @code{catch} or throw handler. If it
969 exits non-locally, that exit determines the continuation.
971 The behaviour of a throw handler is very similar to that of a
972 @code{catch} expression's optional pre-unwind handler. In particular, a
973 throw handler's handler procedure is invoked in the exact dynamic
974 context of the @code{throw} expression, just as a pre-unwind handler is.
975 @code{with-throw-handler} may be seen as a half-@code{catch}: it does
976 everything that a @code{catch} would do until the point where
977 @code{catch} would start unwinding the stack and dynamic context, but
978 then it rethrows to the next innermost @code{catch} or throw handler
981 Note also that since the dynamic context is not unwound, if a
982 @code{with-throw-handler} handler throws to a key that does not match
983 the @code{with-throw-handler} expression's @var{key}, the new throw may
984 be handled by a @code{catch} or throw handler that is @emph{closer} to
985 the throw than the first @code{with-throw-handler}.
987 Here is an example to illustrate this behavior:
992 (with-throw-handler 'b
1004 This code will call @code{inner-handler} and then continue with the
1005 continuation of the inner @code{catch}.
1009 @subsubsection Throwing Exceptions
1011 The @code{throw} primitive is used to throw an exception. One argument,
1012 the @var{key}, is mandatory, and must be a symbol; it indicates the type
1013 of exception that is being thrown. Following the @var{key},
1014 @code{throw} accepts any number of additional arguments, whose meaning
1015 depends on the exception type. The documentation for each possible type
1016 of exception should specify the additional arguments that are expected
1017 for that kind of exception.
1019 @deffn {Scheme Procedure} throw key . args
1020 @deffnx {C Function} scm_throw (key, args)
1021 Invoke the catch form matching @var{key}, passing @var{args} to the
1024 @var{key} is a symbol. It will match catches of the same symbol or of
1027 If there is no handler at all, Guile prints an error and then exits.
1030 When an exception is thrown, it will be caught by the innermost
1031 @code{catch} or throw handler that applies to the type of the thrown
1032 exception; in other words, whose @var{key} is either @code{#t} or the
1033 same symbol as that used in the @code{throw} expression. Once Guile has
1034 identified the appropriate @code{catch} or throw handler, it handles the
1035 exception by applying the relevant handler procedure(s) to the arguments
1036 of the @code{throw}.
1038 If there is no appropriate @code{catch} or throw handler for a thrown
1039 exception, Guile prints an error to the current error port indicating an
1040 uncaught exception, and then exits. In practice, it is quite difficult
1041 to observe this behaviour, because Guile when used interactively
1042 installs a top level @code{catch} handler that will catch all exceptions
1043 and print an appropriate error message @emph{without} exiting. For
1044 example, this is what happens if you try to throw an unhandled exception
1045 in the standard Guile REPL; note that Guile's command loop continues
1046 after the error message:
1049 guile> (throw 'badex)
1050 <unnamed port>:3:1: In procedure gsubr-apply @dots{}
1051 <unnamed port>:3:1: unhandled-exception: badex
1056 The default uncaught exception behaviour can be observed by evaluating a
1057 @code{throw} expression from the shell command line:
1060 $ guile -c "(begin (throw 'badex) (display \"here\\n\"))"
1061 guile: uncaught throw to badex: ()
1066 That Guile exits immediately following the uncaught exception
1067 is shown by the absence of any output from the @code{display}
1068 expression, because Guile never gets to the point of evaluating that
1072 @node Exception Implementation
1073 @subsubsection How Guile Implements Exceptions
1075 It is traditional in Scheme to implement exception systems using
1076 @code{call-with-current-continuation}. Continuations
1077 (@pxref{Continuations}) are such a powerful concept that any other
1078 control mechanism --- including @code{catch} and @code{throw} --- can be
1079 implemented in terms of them.
1081 Guile does not implement @code{catch} and @code{throw} like this,
1082 though. Why not? Because Guile is specifically designed to be easy to
1083 integrate with applications written in C. In a mixed Scheme/C
1084 environment, the concept of @dfn{continuation} must logically include
1085 ``what happens next'' in the C parts of the application as well as the
1086 Scheme parts, and it turns out that the only reasonable way of
1087 implementing continuations like this is to save and restore the complete
1090 So Guile's implementation of @code{call-with-current-continuation} is a
1091 stack copying one. This allows it to interact well with ordinary C
1092 code, but means that creating and calling a continuation is slowed down
1093 by the time that it takes to copy the C stack.
1095 The more targeted mechanism provided by @code{catch} and @code{throw}
1096 does not need to save and restore the C stack because the @code{throw}
1097 always jumps to a location higher up the stack of the code that executes
1098 the @code{throw}. Therefore Guile implements the @code{catch} and
1099 @code{throw} primitives independently of
1100 @code{call-with-current-continuation}, in a way that takes advantage of
1101 this @emph{upwards only} nature of exceptions.
1104 @node Error Reporting
1105 @subsection Procedures for Signaling Errors
1107 Guile provides a set of convenience procedures for signaling error
1108 conditions that are implemented on top of the exception primitives just
1111 @deffn {Scheme Procedure} error msg args @dots{}
1112 Raise an error with key @code{misc-error} and a message constructed by
1113 displaying @var{msg} and writing @var{args}.
1116 @deffn {Scheme Procedure} scm-error key subr message args data
1117 @deffnx {C Function} scm_error_scm (key, subr, message, args, data)
1118 Raise an error with key @var{key}. @var{subr} can be a string
1119 naming the procedure associated with the error, or @code{#f}.
1120 @var{message} is the error message string, possibly containing
1121 @code{~S} and @code{~A} escapes. When an error is reported,
1122 these are replaced by formatting the corresponding members of
1123 @var{args}: @code{~A} (was @code{%s} in older versions of
1124 Guile) formats using @code{display} and @code{~S} (was
1125 @code{%S}) formats using @code{write}. @var{data} is a list or
1126 @code{#f} depending on @var{key}: if @var{key} is
1127 @code{system-error} then it should be a list containing the
1128 Unix @code{errno} value; If @var{key} is @code{signal} then it
1129 should be a list containing the Unix signal number; If
1130 @var{key} is @code{out-of-range} or @code{wrong-type-arg},
1131 it is a list containing the bad value; otherwise
1132 it will usually be @code{#f}.
1135 @deffn {Scheme Procedure} strerror err
1136 @deffnx {C Function} scm_strerror (err)
1137 Return the Unix error message corresponding to @var{err}, an integer
1140 When @code{setlocale} has been called (@pxref{Locales}), the message
1141 is in the language and charset of @code{LC_MESSAGES}. (This is done
1145 @c begin (scm-doc-string "boot-9.scm" "false-if-exception")
1146 @deffn syntax false-if-exception expr
1147 Returns the result of evaluating its argument; however
1148 if an exception occurs then @code{#f} is returned instead.
1154 @subsection Dynamic Wind
1156 For Scheme code, the fundamental procedure to react to non-local entry
1157 and exits of dynamic contexts is @code{dynamic-wind}. C code could
1158 use @code{scm_internal_dynamic_wind}, but since C does not allow the
1159 convenient construction of anonymous procedures that close over
1160 lexical variables, this will be, well, inconvenient.
1162 Therefore, Guile offers the functions @code{scm_dynwind_begin} and
1163 @code{scm_dynwind_end} to delimit a dynamic extent. Within this
1164 dynamic extent, which is called a @dfn{dynwind context}, you can
1165 perform various @dfn{dynwind actions} that control what happens when
1166 the dynwind context is entered or left. For example, you can register
1167 a cleanup routine with @code{scm_dynwind_unwind_handler} that is
1168 executed when the context is left. There are several other more
1169 specialized dynwind actions as well, for example to temporarily block
1170 the execution of asyncs or to temporarily change the current output
1171 port. They are described elsewhere in this manual.
1173 Here is an example that shows how to prevent memory leaks.
1177 /* Suppose there is a function called FOO in some library that you
1178 would like to make available to Scheme code (or to C code that
1179 follows the Scheme conventions).
1181 FOO takes two C strings and returns a new string. When an error has
1182 occurred in FOO, it returns NULL.
1185 char *foo (char *s1, char *s2);
1187 /* SCM_FOO interfaces the C function FOO to the Scheme way of life.
1188 It takes care to free up all temporary strings in the case of
1193 scm_foo (SCM s1, SCM s2)
1195 char *c_s1, *c_s2, *c_res;
1197 scm_dynwind_begin (0);
1199 c_s1 = scm_to_locale_string (s1);
1201 /* Call 'free (c_s1)' when the dynwind context is left.
1203 scm_dynwind_unwind_handler (free, c_s1, SCM_F_WIND_EXPLICITLY);
1205 c_s2 = scm_to_locale_string (s2);
1207 /* Same as above, but more concisely.
1209 scm_dynwind_free (c_s2);
1211 c_res = foo (c_s1, c_s2);
1213 scm_memory_error ("foo");
1217 return scm_take_locale_string (res);
1221 @rnindex dynamic-wind
1222 @deffn {Scheme Procedure} dynamic-wind in_guard thunk out_guard
1223 @deffnx {C Function} scm_dynamic_wind (in_guard, thunk, out_guard)
1224 All three arguments must be 0-argument procedures.
1225 @var{in_guard} is called, then @var{thunk}, then
1228 If, any time during the execution of @var{thunk}, the
1229 dynamic extent of the @code{dynamic-wind} expression is escaped
1230 non-locally, @var{out_guard} is called. If the dynamic extent of
1231 the dynamic-wind is re-entered, @var{in_guard} is called. Thus
1232 @var{in_guard} and @var{out_guard} may be called any number of
1236 (define x 'normal-binding)
1239 (call-with-current-continuation
1245 (lambda () (set! x 'special-binding))
1249 (lambda () (display x) (newline)
1250 (call-with-current-continuation escape)
1251 (display x) (newline)
1256 (lambda () (set! x old-x)))))))
1262 @result{} normal-binding
1267 @result{} a-cont ;; the value of the (define a-cont...)
1269 @result{} normal-binding
1271 @result{} special-binding
1275 @deftp {C Type} scm_t_dynwind_flags
1276 This is an enumeration of several flags that modify the behavior of
1277 @code{scm_dynwind_begin}. The flags are listed in the following
1281 @item SCM_F_DYNWIND_REWINDABLE
1282 The dynamic context is @dfn{rewindable}. This means that it can be
1283 reentered non-locally (via the invocation of a continuation). The
1284 default is that a dynwind context can not be reentered non-locally.
1289 @deftypefn {C Function} void scm_dynwind_begin (scm_t_dynwind_flags flags)
1290 The function @code{scm_dynwind_begin} starts a new dynamic context and
1291 makes it the `current' one.
1293 The @var{flags} argument determines the default behavior of the
1294 context. Normally, use 0. This will result in a context that can not
1295 be reentered with a captured continuation. When you are prepared to
1296 handle reentries, include @code{SCM_F_DYNWIND_REWINDABLE} in
1299 Being prepared for reentry means that the effects of unwind handlers
1300 can be undone on reentry. In the example above, we want to prevent a
1301 memory leak on non-local exit and thus register an unwind handler that
1302 frees the memory. But once the memory is freed, we can not get it
1303 back on reentry. Thus reentry can not be allowed.
1305 The consequence is that continuations become less useful when
1306 non-reenterable contexts are captured, but you don't need to worry
1307 about that too much.
1309 The context is ended either implicitly when a non-local exit happens,
1310 or explicitly with @code{scm_dynwind_end}. You must make sure that a
1311 dynwind context is indeed ended properly. If you fail to call
1312 @code{scm_dynwind_end} for each @code{scm_dynwind_begin}, the behavior
1316 @deftypefn {C Function} void scm_dynwind_end ()
1317 End the current dynamic context explicitly and make the previous one
1321 @deftp {C Type} scm_t_wind_flags
1322 This is an enumeration of several flags that modify the behavior of
1323 @code{scm_dynwind_unwind_handler} and
1324 @code{scm_dynwind_rewind_handler}. The flags are listed in the
1328 @item SCM_F_WIND_EXPLICITLY
1329 @vindex SCM_F_WIND_EXPLICITLY
1330 The registered action is also carried out when the dynwind context is
1331 entered or left locally.
1335 @deftypefn {C Function} void scm_dynwind_unwind_handler (void (*func)(void *), void *data, scm_t_wind_flags flags)
1336 @deftypefnx {C Function} void scm_dynwind_unwind_handler_with_scm (void (*func)(SCM), SCM data, scm_t_wind_flags flags)
1337 Arranges for @var{func} to be called with @var{data} as its arguments
1338 when the current context ends implicitly. If @var{flags} contains
1339 @code{SCM_F_WIND_EXPLICITLY}, @var{func} is also called when the
1340 context ends explicitly with @code{scm_dynwind_end}.
1342 The function @code{scm_dynwind_unwind_handler_with_scm} takes care that
1343 @var{data} is protected from garbage collection.
1346 @deftypefn {C Function} void scm_dynwind_rewind_handler (void (*func)(void *), void *data, scm_t_wind_flags flags)
1347 @deftypefnx {C Function} void scm_dynwind_rewind_handler_with_scm (void (*func)(SCM), SCM data, scm_t_wind_flags flags)
1348 Arrange for @var{func} to be called with @var{data} as its argument when
1349 the current context is restarted by rewinding the stack. When @var{flags}
1350 contains @code{SCM_F_WIND_EXPLICITLY}, @var{func} is called immediately
1353 The function @code{scm_dynwind_rewind_handler_with_scm} takes care that
1354 @var{data} is protected from garbage collection.
1357 @deftypefn {C Function} void scm_dynwind_free (void *mem)
1358 Arrange for @var{mem} to be freed automatically whenever the current
1359 context is exited, whether normally or non-locally.
1360 @code{scm_dynwind_free (mem)} is an equivalent shorthand for
1361 @code{scm_dynwind_unwind_handler (free, mem, SCM_F_WIND_EXPLICITLY)}.
1365 @node Handling Errors
1366 @subsection How to Handle Errors
1368 Error handling is based on @code{catch} and @code{throw}. Errors are
1369 always thrown with a @var{key} and four arguments:
1373 @var{key}: a symbol which indicates the type of error. The symbols used
1374 by libguile are listed below.
1377 @var{subr}: the name of the procedure from which the error is thrown, or
1381 @var{message}: a string (possibly language and system dependent)
1382 describing the error. The tokens @code{~A} and @code{~S} can be
1383 embedded within the message: they will be replaced with members of the
1384 @var{args} list when the message is printed. @code{~A} indicates an
1385 argument printed using @code{display}, while @code{~S} indicates an
1386 argument printed using @code{write}. @var{message} can also be
1387 @code{#f}, to allow it to be derived from the @var{key} by the error
1388 handler (may be useful if the @var{key} is to be thrown from both C and
1392 @var{args}: a list of arguments to be used to expand @code{~A} and
1393 @code{~S} tokens in @var{message}. Can also be @code{#f} if no
1394 arguments are required.
1397 @var{rest}: a list of any additional objects required. e.g., when the
1398 key is @code{'system-error}, this contains the C errno value. Can also
1399 be @code{#f} if no additional objects are required.
1402 In addition to @code{catch} and @code{throw}, the following Scheme
1403 facilities are available:
1405 @deffn {Scheme Procedure} display-error frame port subr message args rest
1406 @deffnx {C Function} scm_display_error (frame, port, subr, message, args, rest)
1407 Display an error message to the output port @var{port}.
1408 @var{frame} is the frame in which the error occurred, @var{subr} is
1409 the name of the procedure in which the error occurred and
1410 @var{message} is the actual error message, which may contain
1411 formatting instructions. These will format the arguments in
1412 the list @var{args} accordingly. @var{rest} is currently
1416 The following are the error keys defined by libguile and the situations
1417 in which they are used:
1421 @cindex @code{error-signal}
1422 @code{error-signal}: thrown after receiving an unhandled fatal signal
1423 such as SIGSEGV, SIGBUS, SIGFPE etc. The @var{rest} argument in the throw
1424 contains the coded signal number (at present this is not the same as the
1425 usual Unix signal number).
1428 @cindex @code{system-error}
1429 @code{system-error}: thrown after the operating system indicates an
1430 error condition. The @var{rest} argument in the throw contains the
1434 @cindex @code{numerical-overflow}
1435 @code{numerical-overflow}: numerical overflow.
1438 @cindex @code{out-of-range}
1439 @code{out-of-range}: the arguments to a procedure do not fall within the
1443 @cindex @code{wrong-type-arg}
1444 @code{wrong-type-arg}: an argument to a procedure has the wrong type.
1447 @cindex @code{wrong-number-of-args}
1448 @code{wrong-number-of-args}: a procedure was called with the wrong number
1452 @cindex @code{memory-allocation-error}
1453 @code{memory-allocation-error}: memory allocation error.
1456 @cindex @code{stack-overflow}
1457 @code{stack-overflow}: stack overflow error.
1460 @cindex @code{regular-expression-syntax}
1461 @code{regular-expression-syntax}: errors generated by the regular
1465 @cindex @code{misc-error}
1466 @code{misc-error}: other errors.
1470 @subsubsection C Support
1472 In the following C functions, @var{SUBR} and @var{MESSAGE} parameters
1473 can be @code{NULL} to give the effect of @code{#f} described above.
1475 @deftypefn {C Function} SCM scm_error (SCM @var{key}, char *@var{subr}, char *@var{message}, SCM @var{args}, SCM @var{rest})
1476 Throw an error, as per @code{scm-error} (@pxref{Error Reporting}).
1479 @deftypefn {C Function} void scm_syserror (char *@var{subr})
1480 @deftypefnx {C Function} void scm_syserror_msg (char *@var{subr}, char *@var{message}, SCM @var{args})
1481 Throw an error with key @code{system-error} and supply @code{errno} in
1482 the @var{rest} argument. For @code{scm_syserror} the message is
1483 generated using @code{strerror}.
1485 Care should be taken that any code in between the failing operation
1486 and the call to these routines doesn't change @code{errno}.
1489 @deftypefn {C Function} void scm_num_overflow (char *@var{subr})
1490 @deftypefnx {C Function} void scm_out_of_range (char *@var{subr}, SCM @var{bad_value})
1491 @deftypefnx {C Function} void scm_wrong_num_args (SCM @var{proc})
1492 @deftypefnx {C Function} void scm_wrong_type_arg (char *@var{subr}, int @var{argnum}, SCM @var{bad_value})
1493 @deftypefnx {C Function} void scm_memory_error (char *@var{subr})
1494 Throw an error with the various keys described above.
1496 For @code{scm_wrong_num_args}, @var{proc} should be a Scheme symbol
1497 which is the name of the procedure incorrectly invoked.
1501 @subsubsection Signalling Type Errors
1503 Every function visible at the Scheme level should aggressively check the
1504 types of its arguments, to avoid misinterpreting a value, and perhaps
1505 causing a segmentation fault. Guile provides some macros to make this
1508 @deftypefn Macro void SCM_ASSERT (int @var{test}, SCM @var{obj}, unsigned int @var{position}, const char *@var{subr})
1509 If @var{test} is zero, signal a ``wrong type argument'' error,
1510 attributed to the subroutine named @var{subr}, operating on the value
1511 @var{obj}, which is the @var{position}'th argument of @var{subr}.
1514 @deftypefn Macro int SCM_ARG1
1515 @deftypefnx Macro int SCM_ARG2
1516 @deftypefnx Macro int SCM_ARG3
1517 @deftypefnx Macro int SCM_ARG4
1518 @deftypefnx Macro int SCM_ARG5
1519 @deftypefnx Macro int SCM_ARG6
1520 @deftypefnx Macro int SCM_ARG7
1521 One of the above values can be used for @var{position} to indicate the
1522 number of the argument of @var{subr} which is being checked.
1523 Alternatively, a positive integer number can be used, which allows to
1524 check arguments after the seventh. However, for parameter numbers up to
1525 seven it is preferable to use @code{SCM_ARGN} instead of the
1526 corresponding raw number, since it will make the code easier to
1530 @deftypefn Macro int SCM_ARGn
1531 Passing a value of zero or @code{SCM_ARGn} for @var{position} allows to
1532 leave it unspecified which argument's type is incorrect. Again,
1533 @code{SCM_ARGn} should be preferred over a raw zero constant.
1537 @node Continuation Barriers
1538 @subsection Continuation Barriers
1540 The non-local flow of control caused by continuations might sometimes
1541 not be wanted. You can use @code{with-continuation-barrier} to erect
1542 fences that continuations can not pass.
1544 @deffn {Scheme Procedure} with-continuation-barrier proc
1545 @deffnx {C Function} scm_with_continuation_barrier (proc)
1546 Call @var{proc} and return its result. Do not allow the invocation of
1547 continuations that would leave or enter the dynamic extent of the call
1548 to @code{with-continuation-barrier}. Such an attempt causes an error
1551 Throws (such as errors) that are not caught from within @var{proc} are
1552 caught by @code{with-continuation-barrier}. In that case, a short
1553 message is printed to the current error port and @code{#f} is returned.
1555 Thus, @code{with-continuation-barrier} returns exactly once.
1558 @deftypefn {C Function} {void *} scm_c_with_continuation_barrier (void *(*func) (void *), void *data)
1559 Like @code{scm_with_continuation_barrier} but call @var{func} on
1560 @var{data}. When an error is caught, @code{NULL} is returned.
1565 @c TeX-master: "guile.texi"