6.13.8.4 Exceptions and C

There are some specific versions of Guile’s original catch and with-throw-handler exception-handling primitives that are still widely used in C code.

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)

C Function: SCM scm_internal_catch (SCM tag, scm_t_catch_body body, void *body_data, scm_t_catch_handler handler, void *handler_data)

The above scm_catch_with_pre_unwind_handler and scm_catch take Scheme procedures as body and handler arguments. scm_c_catch and scm_internal_catch are equivalents taking C functions.

body is called as body (body_data) with a catch on exceptions of the given tag type. If an exception is caught, pre_unwind_handler and handler are called as handler (handler_data, key, args). key and args are the SCM key and argument list from the throw.

body and handler should have the following prototypes. scm_t_catch_body and scm_t_catch_handler are pointer typedefs for these.

SCM body (void *data);
SCM handler (void *data, SCM key, SCM args);

The body_data and handler_data parameters are passed to the respective calls so an application can communicate extra information to those functions.

If the data consists of an SCM object, care should be taken that it isn’t garbage collected while still required. If the SCM is a local C variable, one way to protect it is to pass a pointer to that variable as the data parameter, since the C compiler will then know the value must be held on the stack. Another way is to use scm_remember_upto_here_1 (see Foreign Object Memory Management).

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)

The above scm_with_throw_handler takes Scheme procedures as body (thunk) and handler arguments. scm_c_with_throw_handler is an equivalent taking C functions. See scm_c_catch (see Exceptions and C) for a description of the parameters, the behaviour however of course follows with-throw-handler.