2 '\" Copyright (c) 1990 The Regents of the University of California.
3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 .TH Tcl_Preserve 3 7.5 Tcl "Tcl Library Procedures"
9 .\" The -*- nroff -*- definitions below are for supplemental macros used
10 .\" in Tcl/Tk manual entries.
12 .\" .AP type name in/out ?indent?
13 .\" Start paragraph describing an argument to a library procedure.
14 .\" type is type of argument (int, etc.), in/out is either "in", "out",
15 .\" or "in/out" to describe whether procedure reads or modifies arg,
16 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
17 .\" needed; use .AS below instead)
20 .\" Give maximum sizes of arguments for setting tab stops. Type and
21 .\" name are examples of largest possible arguments that will be passed
22 .\" to .AP later. If args are omitted, default tab stops are used.
25 .\" Start box enclosure. From here until next .BE, everything will be
26 .\" enclosed in one large box.
29 .\" End of box enclosure.
32 .\" Begin code excerpt.
37 .\" .VS ?version? ?br?
38 .\" Begin vertical sidebar, for use in marking newly-changed parts
39 .\" of man pages. The first argument is ignored and used for recording
40 .\" the version when the .VS was added, so that the sidebars can be
41 .\" found and removed when they reach a certain age. If another argument
42 .\" is present, then a line break is forced before starting the sidebar.
45 .\" End of vertical sidebar.
48 .\" Begin an indented unfilled display.
51 .\" End of indented unfilled display.
54 .\" Start of list of standard options for a Tk widget. The manpage
55 .\" argument defines where to look up the standard options; if
56 .\" omitted, defaults to "options". The options follow on successive
57 .\" lines, in three columns separated by tabs.
60 .\" End of list of standard options for a Tk widget.
62 .\" .OP cmdName dbName dbClass
63 .\" Start of description of a specific option. cmdName gives the
64 .\" option's name as specified in the class command, dbName gives
65 .\" the option's name in the option database, and dbClass gives
66 .\" the option's class in the option database.
69 .\" Print arg1 underlined, then print arg2 normally.
72 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
75 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
76 .\" (for trailing punctuation) and then a closing parenthesis.
78 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
82 .\" # Start an argument description
86 . ie !"\\$2"" .TP \\n()Cu
91 \&\\$1 \\fI\\$2\\fP (\\$3)
104 .\" # define tabbing values for .AP
107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
113 .AS Tcl_Interp Tcl_CreateInterp in/out
114 .\" # BS - start boxed text
115 .\" # ^y = starting y location
123 .if n \l'\\n(.lu\(ul'
126 .\" # BE - end boxed text (draw box now)
131 .ie n \l'\\n(^lu\(ul'
133 .\" Draw four-sided box normally, but don't draw top of
134 .\" box if the box started on an earlier page.
136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
146 .\" # VS - start vertical sidebar
147 .\" # ^Y = starting y location
148 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
152 .ie n 'mc \s12\(br\s0
155 .\" # VE - end of vertical sidebar
163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
170 .\" # Special macro to handle page bottom: finish off current
171 .\" # box/sidebar if in box/sidebar mode, then invoked standard
172 .\" # page bottom macro.
179 .\" Draw three-sided box if this is the box's first page,
180 .\" draw two sides but no top otherwise.
181 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
185 .nr ^x \\n(^tu+1v-\\n(^Yu
186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
199 .\" # DS - begin display
205 .\" # DE - end display
211 .\" # SO - start of list of standard options
213 'ie '\\$1'' .ds So \\fBoptions\\fR
214 'el .ds So \\fB\\$1\\fR
215 .SH "STANDARD OPTIONS"
221 .\" # SE - end of list of standard options
226 See the \\*(So manual entry for details on the standard options.
228 .\" # OP - start of full description for a single option
233 Command-Line Name: \\fB\\$1\\fR
234 Database Name: \\fB\\$2\\fR
235 Database Class: \\fB\\$3\\fR
239 .\" # CS - begin code excerpt
245 .\" # CE - end code excerpt
250 .\" # UL - underline word
254 .\" # QW - apply quotation marks to word
256 .ie '\\*(lq'"' ``\\$1''\\$2
257 .\"" fix emacs highlighting
258 .el \\*(lq\\$1\\*(rq\\$2
260 .\" # PQ - apply parens and quotation marks to word
262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
263 .\"" fix emacs highlighting
264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
266 .\" # QR - quoted range
268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
269 .\"" fix emacs highlighting
270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
272 .\" # MT - "empty" string
278 Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it is being used
281 \fB#include <tcl.h>\fR
283 \fBTcl_Preserve\fR(\fIclientData\fR)
285 \fBTcl_Release\fR(\fIclientData\fR)
287 \fBTcl_EventuallyFree\fR(\fIclientData, freeProc\fR)
289 .AS Tcl_FreeProc clientData
290 .AP ClientData clientData in
291 Token describing structure to be freed or reallocated. Usually a pointer
292 to memory for structure.
293 .AP Tcl_FreeProc *freeProc in
294 Procedure to invoke to free \fIclientData\fR.
298 These three procedures help implement a simple reference count mechanism
299 for managing storage. They are designed to solve a problem
300 having to do with widget deletion, but are also useful in many other
301 situations. When a widget is deleted, its
302 widget record (the structure holding information specific to the
303 widget) must be returned to the storage allocator.
304 However, it is possible that the widget record is in active use
305 by one of the procedures on the stack at the time of the deletion.
306 This can happen, for example, if the command associated with a button
307 widget causes the button to be destroyed: an X event causes an
308 event-handling C procedure in the button to be invoked, which in
309 turn causes the button's associated Tcl command to be executed,
310 which in turn causes the button to be deleted, which in turn causes
311 the button's widget record to be de-allocated.
312 Unfortunately, when the Tcl command returns, the button's
313 event-handling procedure will need to reference the
314 button's widget record.
315 Because of this, the widget record must not be freed as part of the
316 deletion, but must be retained until the event-handling procedure has
318 In other situations where the widget is deleted, it may be possible
319 to free the widget record immediately.
321 \fBTcl_Preserve\fR and \fBTcl_Release\fR
322 implement short-term reference counts for their \fIclientData\fR
324 The \fIclientData\fR argument identifies an object and usually
325 consists of the address of a structure.
326 The reference counts guarantee that an object will not be freed
327 until each call to \fBTcl_Preserve\fR for the object has been
328 matched by calls to \fBTcl_Release\fR.
329 There may be any number of unmatched \fBTcl_Preserve\fR calls
332 \fBTcl_EventuallyFree\fR is invoked to free up its \fIclientData\fR
334 It checks to see if there are unmatched \fBTcl_Preserve\fR calls
336 If not, then \fBTcl_EventuallyFree\fR calls \fIfreeProc\fR immediately.
337 Otherwise \fBTcl_EventuallyFree\fR records the fact that \fIclientData\fR
338 needs eventually to be freed.
339 When all calls to \fBTcl_Preserve\fR have been matched with
340 calls to \fBTcl_Release\fR then \fIfreeProc\fR will be called by
341 \fBTcl_Release\fR to do the cleanup.
343 All the work of freeing the object is carried out by \fIfreeProc\fR.
344 \fIFreeProc\fR must have arguments and result that match the
345 type \fBTcl_FreeProc\fR:
348 typedef void \fBTcl_FreeProc\fR(
349 char *\fIblockPtr\fR);
352 The \fIblockPtr\fR argument to \fIfreeProc\fR will be the
353 same as the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR.
354 The type of \fIblockPtr\fR (\fBchar *\fR) is different than the type of the
355 \fIclientData\fR argument to \fBTcl_EventuallyFree\fR for historical
356 reasons, but the value is the same.
358 When the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR
359 refers to storage allocated and returned by a prior call to
360 \fBTcl_Alloc\fR, \fBckalloc\fR, or another function of the Tcl library,
361 then the \fIfreeProc\fR argument should be given the special value of
364 This mechanism can be used to solve the problem described above
365 by placing \fBTcl_Preserve\fR and \fBTcl_Release\fR calls around
366 actions that may cause undesired storage re-allocation. The
367 mechanism is intended only for short-term use (i.e. while procedures
368 are pending on the stack); it will not work efficiently as a
369 mechanism for long-term reference counts.
370 The implementation does not depend in any way on the internal
371 structure of the objects being freed; it keeps the reference
372 counts in a separate structure.
374 Tcl_Interp, Tcl_Alloc
376 free, reference count, storage