Re: Stack unwinding for C code

[Dirk Herrmann]

Marius Vollmer wrote:

> I see.  Hmm.  I have no ideas (yet) about what to do about
> SCM_DEFER_INTS, etc.  But you are right, we should have a plan for
> bringing all things that are related to the dynamic context together.
> So what about separating the API further: there would be only
> scm_begin_frame and an additional function scm_prevent_rewind (or
> scm_prevent_reentry?) could be used like
>
>    scm_begin_frame ();
>    scm_prevent_rewind ();
>    ...
>    scm_end_frame ();
I like this style of interface for its simplicity. But, I am somewhat 
confused since in your proposal below you don't suggest this style of 
interface, but instead describe scm_begin_frame as receiving an 
additional argument with flags. I wouldn't prefer any of the two 
solutions, but I am currently not sure what you actually suggest - 
especially since in the example given below you don't pass any argument 
to scm_begin_frame.

> Sometimes, it is necessary to perform cleanups when the unwinding
> happens.  Frequently, dynamically allocated temporary data structures
> need to be deallocated, for example.
If this document was to be reused in the documentation later, we should 
given an example here.

> - C Function: void scm_begin_frame (int flags)
>
>  Starts a new frame and makes it the 'current' one.  FLAGS determines
>  the default behavior of the frame.  For normal frames, use 0.  This
>  will result in a frame that can not be reentered with a captured
>  continuation.  See below.
>
>  The frame is ended either implicitly when a non-local exit happens,
>  or explicitly with scm_end_frame.
If this style of API is used (that is, passing a 'flags' argument to 
scm_begin_frame instead of having separate functions like 
scm_prevent_rewind and similar), then I suggest to use an enumeration 
type with all possible flags instead of an int type. This improves both 
type safety and readability of the code using scm_begin_frame. The same 
applies to the 'explicit' argument to scm_on_unwind and scm_on_rewind.

> - C Function: void scm_on_unwind (void (*func)(void *), void *data,
>                                  int explicit)
>
>  Arranges for FUNC to be called with DATA as its arguments when the
>  current frame ends implicitly.  If EXPLICIT is non-zero, FUNC is
>  also called when the frame ends explicitly.
It is a nice coincidence that 'free' matches the void (*func) (void *) 
signature, especially since free will probably be one of the most 
frequently used functions with scm_on_unwind. fclose, however, does not 
match and is another candidate that may be commonly used. Unfortunately 
it wouldn't be standard conforming to just cast fclose to match the 
signature. I suggest that (in addition to the generic scm_on_unwind) for 
a limited set of common functions we provide specialized 
scm_on_unwind_xxx functions, like:

scm_on_unwind_free (void *data, int explicit); // could simply be 
#defined to scm_on_unwind
scm_on_unwind_fclose (FILE* fp, int explicit); // on some architectures 
this may also safely be #defined to scm_on_unwind
// maybe there are other typical cleanup functions...

Then, scm_on_unwind_free could either simply be #defined to 
scm_on_unwind, or - if it brings some performance and code size benefit 
to avoid passing the additional argument - provided as a special 
implementation. On some architectures it may also be an option to just 
#define scm_on_unwind_fclose to scm_on_unwind.

Best regards
Dirk Herrmann