1 | '\" |
---|
2 | '\" Copyright (c) 1990 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
4 | '\" |
---|
5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
7 | '\" |
---|
8 | '\" RCS: @(#) $Id: Preserve.3,v 1.6 2007/12/13 15:22:31 dgp Exp $ |
---|
9 | '\" |
---|
10 | .so man.macros |
---|
11 | .TH Tcl_Preserve 3 7.5 Tcl "Tcl Library Procedures" |
---|
12 | .BS |
---|
13 | .SH NAME |
---|
14 | Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it is being used |
---|
15 | .SH SYNOPSIS |
---|
16 | .nf |
---|
17 | \fB#include <tcl.h>\fR |
---|
18 | .sp |
---|
19 | \fBTcl_Preserve\fR(\fIclientData\fR) |
---|
20 | .sp |
---|
21 | \fBTcl_Release\fR(\fIclientData\fR) |
---|
22 | .sp |
---|
23 | \fBTcl_EventuallyFree\fR(\fIclientData, freeProc\fR) |
---|
24 | .SH ARGUMENTS |
---|
25 | .AS Tcl_FreeProc clientData |
---|
26 | .AP ClientData clientData in |
---|
27 | Token describing structure to be freed or reallocated. Usually a pointer |
---|
28 | to memory for structure. |
---|
29 | .AP Tcl_FreeProc *freeProc in |
---|
30 | Procedure to invoke to free \fIclientData\fR. |
---|
31 | .BE |
---|
32 | |
---|
33 | .SH DESCRIPTION |
---|
34 | .PP |
---|
35 | These three procedures help implement a simple reference count mechanism |
---|
36 | for managing storage. They are designed to solve a problem |
---|
37 | having to do with widget deletion, but are also useful in many other |
---|
38 | situations. When a widget is deleted, its |
---|
39 | widget record (the structure holding information specific to the |
---|
40 | widget) must be returned to the storage allocator. |
---|
41 | However, it is possible that the widget record is in active use |
---|
42 | by one of the procedures on the stack at the time of the deletion. |
---|
43 | This can happen, for example, if the command associated with a button |
---|
44 | widget causes the button to be destroyed: an X event causes an |
---|
45 | event-handling C procedure in the button to be invoked, which in |
---|
46 | turn causes the button's associated Tcl command to be executed, |
---|
47 | which in turn causes the button to be deleted, which in turn causes |
---|
48 | the button's widget record to be de-allocated. |
---|
49 | Unfortunately, when the Tcl command returns, the button's |
---|
50 | event-handling procedure will need to reference the |
---|
51 | button's widget record. |
---|
52 | Because of this, the widget record must not be freed as part of the |
---|
53 | deletion, but must be retained until the event-handling procedure has |
---|
54 | finished with it. |
---|
55 | In other situations where the widget is deleted, it may be possible |
---|
56 | to free the widget record immediately. |
---|
57 | .PP |
---|
58 | \fBTcl_Preserve\fR and \fBTcl_Release\fR |
---|
59 | implement short-term reference counts for their \fIclientData\fR |
---|
60 | argument. |
---|
61 | The \fIclientData\fR argument identifies an object and usually |
---|
62 | consists of the address of a structure. |
---|
63 | The reference counts guarantee that an object will not be freed |
---|
64 | until each call to \fBTcl_Preserve\fR for the object has been |
---|
65 | matched by calls to \fBTcl_Release\fR. |
---|
66 | There may be any number of unmatched \fBTcl_Preserve\fR calls |
---|
67 | in effect at once. |
---|
68 | .PP |
---|
69 | \fBTcl_EventuallyFree\fR is invoked to free up its \fIclientData\fR |
---|
70 | argument. |
---|
71 | It checks to see if there are unmatched \fBTcl_Preserve\fR calls |
---|
72 | for the object. |
---|
73 | If not, then \fBTcl_EventuallyFree\fR calls \fIfreeProc\fR immediately. |
---|
74 | Otherwise \fBTcl_EventuallyFree\fR records the fact that \fIclientData\fR |
---|
75 | needs eventually to be freed. |
---|
76 | When all calls to \fBTcl_Preserve\fR have been matched with |
---|
77 | calls to \fBTcl_Release\fR then \fIfreeProc\fR will be called by |
---|
78 | \fBTcl_Release\fR to do the cleanup. |
---|
79 | .PP |
---|
80 | All the work of freeing the object is carried out by \fIfreeProc\fR. |
---|
81 | \fIFreeProc\fR must have arguments and result that match the |
---|
82 | type \fBTcl_FreeProc\fR: |
---|
83 | .CS |
---|
84 | typedef void Tcl_FreeProc(char *\fIblockPtr\fR); |
---|
85 | .CE |
---|
86 | The \fIblockPtr\fR argument to \fIfreeProc\fR will be the |
---|
87 | same as the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR. |
---|
88 | The type of \fIblockPtr\fR (\fBchar *\fR) is different than the type of the |
---|
89 | \fIclientData\fR argument to \fBTcl_EventuallyFree\fR for historical |
---|
90 | reasons, but the value is the same. |
---|
91 | .PP |
---|
92 | When the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR |
---|
93 | refers to storage allocated and returned by a prior call to |
---|
94 | \fBTcl_Alloc\fR, \fBckalloc\fR, or another function of the Tcl library, |
---|
95 | then the \fIfreeProc\fR argument should be given the special value of |
---|
96 | \fBTCL_DYNAMIC\fR. |
---|
97 | .PP |
---|
98 | This mechanism can be used to solve the problem described above |
---|
99 | by placing \fBTcl_Preserve\fR and \fBTcl_Release\fR calls around |
---|
100 | actions that may cause undesired storage re-allocation. The |
---|
101 | mechanism is intended only for short-term use (i.e. while procedures |
---|
102 | are pending on the stack); it will not work efficiently as a |
---|
103 | mechanism for long-term reference counts. |
---|
104 | The implementation does not depend in any way on the internal |
---|
105 | structure of the objects being freed; it keeps the reference |
---|
106 | counts in a separate structure. |
---|
107 | |
---|
108 | .SH "SEE ALSO" |
---|
109 | Tcl_Interp, Tcl_Alloc |
---|
110 | |
---|
111 | .SH KEYWORDS |
---|
112 | free, reference count, storage |
---|