1Tcl_Preserve(3)             Tcl Library Procedures             Tcl_Preserve(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_Preserve,  Tcl_Release,  Tcl_EventuallyFree - avoid freeing storage
9       while it is being used
10

SYNOPSIS

12       #include <tcl.h>
13
14       Tcl_Preserve(clientData)
15
16       Tcl_Release(clientData)
17
18       Tcl_EventuallyFree(clientData, freeProc)
19

ARGUMENTS

21       ClientData clientData (in)            Token describing structure to  be
22                                             freed  or reallocated.  Usually a
23                                             pointer to memory for structure.
24
25       Tcl_FreeProc *freeProc (in)           Procedure  to  invoke   to   free
26                                             clientData.
27______________________________________________________________________________
28

DESCRIPTION

30       These  three  procedures help implement a simple reference count mecha‐
31       nism for managing storage.  They are designed to solve a problem having
32       to  do  with  widget deletion, but are also useful in many other situa‐
33       tions.  When a widget is deleted,  its  widget  record  (the  structure
34       holding  information  specific  to  the widget) must be returned to the
35       storage allocator.  However, it is possible that the widget  record  is
36       in  active use by one of the procedures on the stack at the time of the
37       deletion.  This can happen, for example, if the command associated with
38       a  button  widget causes the button to be destroyed:  an X event causes
39       an event-handling C procedure in the button to  be  invoked,  which  in
40       turn  causes  the button's associated Tcl command to be executed, which
41       in turn causes the button to be deleted, which in turn causes the  but‐
42       ton's  widget  record  to be de-allocated.  Unfortunately, when the Tcl
43       command returns, the button's event-handling  procedure  will  need  to
44       reference  the  button's  widget  record.   Because of this, the widget
45       record must not be freed as part of the deletion, but must be  retained
46       until the event-handling procedure has finished with it.  In other sit‐
47       uations where the widget is deleted, it may be  possible  to  free  the
48       widget record immediately.
49
50       Tcl_Preserve  and Tcl_Release implement short-term reference counts for
51       their clientData argument.  The clientData argument identifies  an  ob‐
52       ject and usually consists of the address of a structure.  The reference
53       counts guarantee that an object will not be freed until  each  call  to
54       Tcl_Preserve  for  the object has been matched by calls to Tcl_Release.
55       There may be any number of unmatched Tcl_Preserve calls  in  effect  at
56       once.
57
58       Tcl_EventuallyFree  is  invoked to free up its clientData argument.  It
59       checks to see if there are unmatched Tcl_Preserve calls for the object.
60       If  not, then Tcl_EventuallyFree calls freeProc immediately.  Otherwise
61       Tcl_EventuallyFree records the fact that clientData needs eventually to
62       be  freed.  When all calls to Tcl_Preserve have been matched with calls
63       to Tcl_Release then freeProc will be called by Tcl_Release  to  do  the
64       cleanup.
65
66       All  the work of freeing the object is carried out by freeProc.  FreeP‐
67       roc must have arguments and result that match the type Tcl_FreeProc:
68
69              typedef void Tcl_FreeProc(
70                      char *blockPtr);
71
72       The blockPtr argument to freeProc will be the same  as  the  clientData
73       argument  to Tcl_EventuallyFree.  The type of blockPtr (char *) is dif‐
74       ferent than the type of the clientData argument  to  Tcl_EventuallyFree
75       for historical reasons, but the value is the same.
76
77       When  the  clientData  argument to Tcl_EventuallyFree refers to storage
78       allocated and returned by a prior call to Tcl_Alloc,  ckalloc,  or  an‐
79       other function of the Tcl library, then the freeProc argument should be
80       given the special value of TCL_DYNAMIC.
81
82       This mechanism can be used to solve  the  problem  described  above  by
83       placing  Tcl_Preserve  and  Tcl_Release  calls  around actions that may
84       cause undesired storage re-allocation.  The mechanism is intended  only
85       for  short-term  use  (i.e. while procedures are pending on the stack);
86       it will not work efficiently as a  mechanism  for  long-term  reference
87       counts.   The implementation does not depend in any way on the internal
88       structure of the objects being freed;  it keeps the reference counts in
89       a separate structure.
90

SEE ALSO

92       Tcl_Interp, Tcl_Alloc
93

KEYWORDS

95       free, reference count, storage
96
97
98
99Tcl                                   7.5                      Tcl_Preserve(3)
Impressum