[25] | 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 |
---|