115 lines
4.7 KiB
Groff
115 lines
4.7 KiB
Groff
|
'\"
|
||
|
|
'\" Copyright (c) 1990 The Regents of the University of California.
|
||
|
|
'\" All rights reserved.
|
||
|
|
'\"
|
||
|
|
'\" Permission is hereby granted, without written agreement and without
|
||
|
|
'\" license or royalty fees, to use, copy, modify, and distribute this
|
||
|
|
'\" documentation for any purpose, provided that the above copyright
|
||
|
|
'\" notice and the following two paragraphs appear in all copies.
|
||
|
|
'\"
|
||
|
|
'\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
|
||
|
|
'\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
|
||
|
|
'\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
|
||
|
|
'\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||
|
|
'\"
|
||
|
|
'\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
|
||
|
|
'\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
|
||
|
|
'\" AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
|
||
|
|
'\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
|
||
|
|
'\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
|
||
|
|
'\"
|
||
|
|
'\" $Header: /user6/ouster/wish/man/RCS/Preserve.3,v 1.5 93/04/01 09:41:54 ouster Exp $ SPRITE (Berkeley)
|
||
|
|
'\"
|
||
|
|
.so man.macros
|
||
|
|
.HS Tk_Preserve tkc
|
||
|
|
.BS
|
||
|
|
.SH NAME
|
||
|
|
Tk_Preserve, Tk_Release, Tk_EventuallyFree \- avoid freeing storage while it's being used
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.nf
|
||
|
|
\fB#include <tk.h>\fR
|
||
|
|
.sp
|
||
|
|
\fBTk_Preserve\fR(\fIclientData\fR)
|
||
|
|
.sp
|
||
|
|
\fBTk_Release\fR(\fIclientData\fR)
|
||
|
|
.sp
|
||
|
|
\fBTk_EventuallyFree\fR(\fIclientData, freeProc\fR)
|
||
|
|
.SH ARGUMENTS
|
||
|
|
.AS Tk_FreeProc clientData
|
||
|
|
.AP ClientData clientData in
|
||
|
|
Token describing structure to be freed or reallocated. Usually a pointer
|
||
|
|
to memory for structure.
|
||
|
|
.AP Tk_FreeProc *freeProc in
|
||
|
|
Procedure to invoke to free \fIclientData\fR.
|
||
|
|
.BE
|
||
|
|
|
||
|
|
.SH DESCRIPTION
|
||
|
|
.PP
|
||
|
|
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. 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.
|
||
|
|
.PP
|
||
|
|
\fBTk_Preserve\fR and \fBTk_Release\fR
|
||
|
|
implement short-term reference counts for their \fIclientData\fR
|
||
|
|
argument.
|
||
|
|
The \fIclientData\fR 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 \fBTk_Preserve\fR for the object has been
|
||
|
|
matched by calls to \fBTk_Release\fR.
|
||
|
|
There may be any number of unmatched \fBTk_Preserve\fR calls
|
||
|
|
in effect at once.
|
||
|
|
.PP
|
||
|
|
\fBTk_EventuallyFree\fR is invoked to free up its \fIclientData\fR
|
||
|
|
argument.
|
||
|
|
It checks to see if there are unmatched \fBTk_Preserve\fR calls
|
||
|
|
for the object.
|
||
|
|
If not, then \fBTk_EventuallyFree\fR calls \fIfreeProc\fR immediately.
|
||
|
|
Otherwise \fBTk_EventuallyFree\fR records the fact that \fIclientData\fR
|
||
|
|
needs eventually to be freed.
|
||
|
|
When all calls to \fBTk_Preserve\fR have been matched with
|
||
|
|
calls to \fBTk_Release\fR then \fIfreeProc\fR will be called by
|
||
|
|
\fBTk_Release\fR to do the cleanup.
|
||
|
|
.PP
|
||
|
|
All the work of freeing the object is carried out by \fIfreeProc\fR.
|
||
|
|
\fIFreeProc\fR must have arguments and result that match the
|
||
|
|
type \fBTk_FreeProc\fR:
|
||
|
|
.nf
|
||
|
|
.RS
|
||
|
|
typedef void Tk_FreeProc(ClientData \fIclientData\fR);
|
||
|
|
.RE
|
||
|
|
.fi
|
||
|
|
The \fIclientData\fR argument to \fIfreeProc\fR will be the
|
||
|
|
same as the \fIclientData\fR argument to \fBTk_EventuallyFree\fR.
|
||
|
|
.PP
|
||
|
|
This mechanism can be used to solve the problem described above
|
||
|
|
by placing \fBTk_Preserve\fR and \fBTk_Release\fR 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.
|
||
|
|
|
||
|
|
.SH KEYWORDS
|
||
|
|
free, reference count, storage
|