15.2 Dynamic Binding; The specbinding Stack; Unwind-Protects

struct specbinding
{
  Lisp_Object symbol;
  Lisp_Object old_value;
  Lisp_Object (*func) (Lisp_Object); /* for unwind-protect */
};

struct specbinding is used for local-variable bindings and unwind-protects. specpdl holds an array of struct specbinding’s, specpdl_ptr points to the beginning of the free bindings in the array, specpdl_size specifies the total number of binding slots in the array, and max_specpdl_size specifies the maximum number of bindings the array can be expanded to hold. grow_specpdl() increases the size of the specpdl array, multiplying its size by 2 but never exceeding max_specpdl_size (except that if this number is less than 400, it is first set to 400).

specbind() binds a symbol to a value and is used for local variables and let forms. The symbol and its old value (which might be Qunbound, indicating no prior value) are recorded in the specpdl array, and specpdl_size is increased by 1.

record_unwind_protect() implements an unwind-protect, which, when placed around a section of code, ensures that some specified cleanup routine will be executed even if the code exits abnormally (e.g. through a throw or quit). record_unwind_protect() simply adds a new specbinding to the specpdl array and stores the appropriate information in it. The cleanup routine can either be a C function, which is stored in the func field, or a progn form, which is stored in the old_value field.

unbind_to() removes specbindings from the specpdl array until the specified position is reached. Each specbinding can be one of three types:

1. an unwind-protect with a C cleanup function (func is not 0, and old_value holds an argument to be passed to the function);
2. an unwind-protect with a Lisp form (func is 0, symbol is nil, and old_value holds the form to be executed with Fprogn()); or
3. a local-variable binding (func is 0, symbol is not nil, and old_value holds the old value, which is stored as the symbol’s value).