Interaction with the garbage collector and stack-shifter

C-functions that manipulate Prolog terms manipulate pointers to the Prolog runtime stacks. Prolog implements two mechanisms for avoiding stack overflow: garbage collection and stack expansion. On machines that allow for it, Prolog will use virtual memory management to detect stack overflow and expand the runtime stacks. On other machines Prolog will reallocate the stacks and update all pointers to them. To do so, Prolog needs to know which variables of active C-functions contain references to Prolog data.

C-variables may be registered with the Prolog engine using the macro PL_lock() and unregistered using PL_unlock(). These macros should be perfectly balanced and any term locked in a C-function needs to be unlocked before control is passed back to Prolog.

A C-variable that is registered must hold valid Prolog data or `0'.

void

PL_lock( term_t)
  Register the named C-variable with the Prolog engine. The variable should hold a valid Prolog term. The value of the variable may be changed while it remains locked. Each locked variable must be unlocked using PL_unlock(). Locking and unlocking must be balanced.

void

PL_unlock( term_t)
  Unlock a locked variable. If the named variable is not the most recently locked variable an error message is printed. If a foreign function leaves variables unlocked an error message is issued as well.

• When is locking necessary