doco scm_internal_catch

[Kevin Ryde]

A few words adapted from throw.c for the end of the Catch node, and
for the Lazy Catch node just after the lazy-catch / scm_lazy_catch
definition.

I'm not sure I quite follow the caveat about garbage collection of the
data parameter.

If an SCM_UNPACK is done to turn an SCM into a value for the data
pointer parameter, is that in theory not going to be spotted by gc?

Or is it merely that if the data pointer is to a malloced block or the
like, that such an area is unknown to the gc?



 - 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' takes Scheme procedures as body and handler
     arguments.  `scm_internal_catch' is an equivalent 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, HANDLER is called
     `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' (*note Remembering During
     Operations::).



 - C Function: SCM scm_internal_lazy_catch (SCM tag, scm_t_catch_body
          body, void *body_data, scm_t_catch_handler handler, void
          *handler_data)
     The above `scm_lazy_catch' takes Scheme procedures as body and
     handler arguments.  `scm_internal_lazy_catch' is an equivalent
     taking C functions.  See `scm_internal_catch' (*note Catch::) for
     a description of the parameters, though the behaviour however of
     course follows `lazy-catch'.