Tcl_Preserve(3) Tcl (7.5) Tcl_Preserve(3)
_________________________________________________________________
NAME
Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree - avoid
freeing storage while it's being used
SYNOPSIS
#include <tcl.h>
Tcl_Preserve(clientData)Tcl_Release(clientData)
Tcl_EventuallyFree(clientData, freeProc)
ARGUMENTS
ClientData clientData (in) Token describing
structure to be freed
or reallocated.
Usually a pointer to
memory for structure.
Tcl_FreeProc *freeProc (in) Procedure to invoke to
free clientData.
_________________________________________________________________
DESCRIPTION
These three procedures help implement a simple reference
count mechanism for managing storage. They are designed to
solve a problem having to do with widget deletion, but are
also useful in many other situations. When a widget is
deleted, its widget record (the structure holding
information specific to the widget) must be returned to the
storage allocator. However, it's possible that the widget
record is in active use by one of the procedures on the
stack at the time of the deletion. This can happen, for
example, if the command associated with a button widget
causes the button to be destroyed: an X event causes an
event-handling C procedure in the button to be invoked,
which in turn causes the button's associated Tcl command to
be executed, which in turn causes the button to be deleted,
which in turn causes the button's widget record to be de-
allocated. Unfortunately, when the Tcl command returns, the
button's event-handling procedure will need to reference the
button's widget record. Because of this, the widget record
must not be freed as part of the deletion, but must be
retained until the event-handling procedure has finished
with it. In other situations where the widget is deleted,
it may be possible to free the widget record immediately.
Tcl_Preserve and Tcl_Release implement short-term reference
Page 1 (printed 2/19/99)
Tcl_Preserve(3) Tcl (7.5) Tcl_Preserve(3)
counts for their clientData argument. The clientData
argument identifies an object and usually consists of the
address of a structure. The reference counts guarantee that
an object will not be freed until each call to Tcl_Preserve
for the object has been matched by calls to Tcl_Release.
There may be any number of unmatched Tcl_Preserve calls in
effect at once.
Tcl_EventuallyFree is invoked to free up its clientData
argument. It checks to see if there are unmatched
Tcl_Preserve calls for the object. If not, then
Tcl_EventuallyFree calls freeProc immediately. Otherwise
Tcl_EventuallyFree records the fact that clientData needs
eventually to be freed. When all calls to Tcl_Preserve have
been matched with calls to Tcl_Release then freeProc will be
called by Tcl_Release to do the cleanup.
All the work of freeing the object is carried out by
freeProc. FreeProc must have arguments and result that
match the type Tcl_FreeProc:
typedef void Tcl_FreeProc(char *blockPtr);
The blockPtr argument to freeProc will be the same as the
clientData argument to Tcl_EventuallyFree. The type of
blockPtr (char *) is different than the type of the
clientData argument to Tcl_EventuallyFree for historical
reasons, but the value is the same.
This mechanism can be used to solve the problem described
above by placing Tcl_Preserve and Tcl_Release calls around
actions that may cause undesired storage re-allocation. The
mechanism is intended only for short-term use (i.e. while
procedures are pending on the stack); it will not work
efficiently as a mechanism for long-term reference counts.
The implementation does not depend in any way on the
internal structure of the objects being freed; it keeps the
reference counts in a separate structure.
KEYWORDS
free, reference count, storage
Page 2 (printed 2/19/99)
