| 1 |
578 |
markom |
'\"
|
| 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.1.1.1 2002-01-16 10:25:24 markom 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's being used
|
| 15 |
|
|
.SH SYNOPSIS
|
| 16 |
|
|
.nf
|
| 17 |
|
|
\fB#include \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's 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 |
|
|
This mechanism can be used to solve the problem described above
|
| 93 |
|
|
by placing \fBTcl_Preserve\fR and \fBTcl_Release\fR calls around
|
| 94 |
|
|
actions that may cause undesired storage re-allocation. The
|
| 95 |
|
|
mechanism is intended only for short-term use (i.e. while procedures
|
| 96 |
|
|
are pending on the stack); it will not work efficiently as a
|
| 97 |
|
|
mechanism for long-term reference counts.
|
| 98 |
|
|
The implementation does not depend in any way on the internal
|
| 99 |
|
|
structure of the objects being freed; it keeps the reference
|
| 100 |
|
|
counts in a separate structure.
|
| 101 |
|
|
|
| 102 |
|
|
.SH KEYWORDS
|
| 103 |
|
|
free, reference count, storage
|
