ALPHALINUX5/util/ALPHALINUX5/man/man3/Tcl_Preserve.3

   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.2 1998/09/14 18:39:49 stanton Exp $
   9 '\"
  10 '\" The definitions below are for supplemental macros used in Tcl/Tk
  11 '\" manual entries.
  12 '\"
  13 '\" .AP type name in/out ?indent?
  14 '\"     Start paragraph describing an argument to a library procedure.
  15 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
  16 '\"     or "in/out" to describe whether procedure reads or modifies arg,
  17 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  18 '\"     needed;  use .AS below instead)
  19 '\"
  20 '\" .AS ?type? ?name?
  21 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
  22 '\"     name are examples of largest possible arguments that will be passed
  23 '\"     to .AP later.  If args are omitted, default tab stops are used.
  24 '\"
  25 '\" .BS
  26 '\"     Start box enclosure.  From here until next .BE, everything will be
  27 '\"     enclosed in one large box.
  28 '\"
  29 '\" .BE
  30 '\"     End of box enclosure.
  31 '\"
  32 '\" .CS
  33 '\"     Begin code excerpt.
  34 '\"
  35 '\" .CE
  36 '\"     End code excerpt.
  37 '\"
  38 '\" .VS ?version? ?br?
  39 '\"     Begin vertical sidebar, for use in marking newly-changed parts
  40 '\"     of man pages.  The first argument is ignored and used for recording
  41 '\"     the version when the .VS was added, so that the sidebars can be
  42 '\"     found and removed when they reach a certain age.  If another argument
  43 '\"     is present, then a line break is forced before starting the sidebar.
  44 '\"
  45 '\" .VE
  46 '\"     End of vertical sidebar.
  47 '\"
  48 '\" .DS
  49 '\"     Begin an indented unfilled display.
  50 '\"
  51 '\" .DE
  52 '\"     End of indented unfilled display.
  53 '\"
  54 '\" .SO
  55 '\"     Start of list of standard options for a Tk widget.  The
  56 '\"     options follow on successive lines, in four columns separated
  57 '\"     by tabs.
  58 '\"
  59 '\" .SE
  60 '\"     End of list of standard options for a Tk widget.
  61 '\"
  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.
  67 '\"
  68 '\" .UL arg1 arg2
  69 '\"     Print arg1 underlined, then print arg2 normally.
  70 '\"
  71 '\" RCS: @(#) $Id: man.macros,v 1.3 1999/04/16 00:46:35 stanton Exp $
  72 '\"
  73 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  74 .if t .wh -1.3i ^B
  75 .nr ^l \n(.l
  76 .ad b
  77 '\"     # Start an argument description
  78 .de AP
  79 .ie !"\\$4"" .TP \\$4
  80 .el \{\
  81 .   ie !"\\$2"" .TP \\n()Cu
  82 .   el          .TP 15
  83 .\}
  84 .ta \\n()Au \\n()Bu
  85 .ie !"\\$3"" \{\
  86 \&\\$1  \\fI\\$2\\fP    (\\$3)
  87 .\".b
  88 .\}
  89 .el \{\
  90 .br
  91 .ie !"\\$2"" \{\
  92 \&\\$1  \\fI\\$2\\fP
  93 .\}
  94 .el \{\
  95 \&\\fI\\$1\\fP
  96 .\}
  97 .\}
  98 ..
  99 '\"     # define tabbing values for .AP
 100 .de AS
 101 .nr )A 10n
 102 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 103 .nr )B \\n()Au+15n
 104 .\"
 105 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 106 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 107 ..
 108 .AS Tcl_Interp Tcl_CreateInterp in/out
 109 '\"     # BS - start boxed text
 110 '\"     # ^y = starting y location
 111 '\"     # ^b = 1
 112 .de BS
 113 .br
 114 .mk ^y
 115 .nr ^b 1u
 116 .if n .nf
 117 .if n .ti 0
 118 .if n \l'\\n(.lu\(ul'
 119 .if n .fi
 120 ..
 121 '\"     # BE - end boxed text (draw box now)
 122 .de BE
 123 .nf
 124 .ti 0
 125 .mk ^t
 126 .ie n \l'\\n(^lu\(ul'
 127 .el \{\
 128 .\"     Draw four-sided box normally, but don't draw top of
 129 .\"     box if the box started on an earlier page.
 130 .ie !\\n(^b-1 \{\
 131 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 132 .\}
 133 .el \}\
 134 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 135 .\}
 136 .\}
 137 .fi
 138 .br
 139 .nr ^b 0
 140 ..
 141 '\"     # VS - start vertical sidebar
 142 '\"     # ^Y = starting y location
 143 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 144 .de VS
 145 .if !"\\$2"" .br
 146 .mk ^Y
 147 .ie n 'mc \s12\(br\s0
 148 .el .nr ^v 1u
 149 ..
 150 '\"     # VE - end of vertical sidebar
 151 .de VE
 152 .ie n 'mc
 153 .el \{\
 154 .ev 2
 155 .nf
 156 .ti 0
 157 .mk ^t
 158 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 159 .sp -1
 160 .fi
 161 .ev
 162 .\}
 163 .nr ^v 0
 164 ..
 165 '\"     # Special macro to handle page bottom:  finish off current
 166 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
 167 '\"     # page bottom macro.
 168 .de ^B
 169 .ev 2
 170 'ti 0
 171 'nf
 172 .mk ^t
 173 .if \\n(^b \{\
 174 .\"     Draw three-sided box if this is the box's first page,
 175 .\"     draw two sides but no top otherwise.
 176 .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
 177 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 178 .\}
 179 .if \\n(^v \{\
 180 .nr ^x \\n(^tu+1v-\\n(^Yu
 181 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 182 .\}
 183 .bp
 184 'fi
 185 .ev
 186 .if \\n(^b \{\
 187 .mk ^y
 188 .nr ^b 2
 189 .\}
 190 .if \\n(^v \{\
 191 .mk ^Y
 192 .\}
 193 ..
 194 '\"     # DS - begin display
 195 .de DS
 196 .RS
 197 .nf
 198 .sp
 199 ..
 200 '\"     # DE - end display
 201 .de DE
 202 .fi
 203 .RE
 204 .sp
 205 ..
 206 '\"     # SO - start of list of standard options
 207 .de SO
 208 .SH "STANDARD OPTIONS"
 209 .LP
 210 .nf
 211 .ta 4c 8c 12c
 212 .ft B
 213 ..
 214 '\"     # SE - end of list of standard options
 215 .de SE
 216 .fi
 217 .ft R
 218 .LP
 219 See the \\fBoptions\\fR manual entry for details on the standard options.
 220 ..
 221 '\"     # OP - start of full description for a single option
 222 .de OP
 223 .LP
 224 .nf
 225 .ta 4c
 226 Command-Line Name:      \\fB\\$1\\fR
 227 Database Name:  \\fB\\$2\\fR
 228 Database Class: \\fB\\$3\\fR
 229 .fi
 230 .IP
 231 ..
 232 '\"     # CS - begin code excerpt
 233 .de CS
 234 .RS
 235 .nf
 236 .ta .25i .5i .75i 1i
 237 ..
 238 '\"     # CE - end code excerpt
 239 .de CE
 240 .fi
 241 .RE
 242 ..
 243 .de UL
 244 \\$1\l'|0\(ul'\\$2
 245 ..
 246 .TH Tcl_Preserve 3 7.5 Tcl "Tcl Library Procedures"
 247 .BS
 248 .SH NAME
 249 Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it's being used
 250 .SH SYNOPSIS
 251 .nf
 252 \fB#include <tcl.h>\fR
 253 .sp
 254 \fBTcl_Preserve\fR(\fIclientData\fR)
 255 .sp
 256 \fBTcl_Release\fR(\fIclientData\fR)
 257 .sp
 258 \fBTcl_EventuallyFree\fR(\fIclientData, freeProc\fR)
 259 .SH ARGUMENTS
 260 .AS Tcl_FreeProc clientData
 261 .AP ClientData clientData in
 262 Token describing structure to be freed or reallocated.  Usually a pointer
 263 to memory for structure.
 264 .AP Tcl_FreeProc *freeProc in
 265 Procedure to invoke to free \fIclientData\fR.
 266 .BE
 267
 268 .SH DESCRIPTION
 269 .PP
 270 These three procedures help implement a simple reference count mechanism
 271 for managing storage.  They are designed to solve a problem
 272 having to do with widget deletion, but are also useful in many other
 273 situations.  When a widget is deleted, its
 274 widget record (the structure holding information specific to the
 275 widget) must be returned to the storage allocator.
 276 However, it's possible that the widget record is in active use
 277 by one of the procedures on the stack at the time of the deletion.
 278 This can happen, for example, if the command associated with a button
 279 widget causes the button to be destroyed:  an X event causes an
 280 event-handling C procedure in the button to be invoked, which in
 281 turn causes the button's associated Tcl command to be executed,
 282 which in turn causes the button to be deleted, which in turn causes
 283 the button's widget record to be de-allocated.
 284 Unfortunately, when the Tcl command returns, the button's
 285 event-handling procedure will need to reference the
 286 button's widget record.
 287 Because of this, the widget record must not be freed as part of the
 288 deletion, but must be retained until the event-handling procedure has
 289 finished with it.
 290 In other situations where the widget is deleted, it may be possible
 291 to free the widget record immediately.
 292 .PP
 293 \fBTcl_Preserve\fR and \fBTcl_Release\fR
 294 implement short-term reference counts for their \fIclientData\fR
 295 argument.
 296 The \fIclientData\fR argument identifies an object and usually
 297 consists of the address of a structure.
 298 The reference counts guarantee that an object will not be freed
 299 until each call to \fBTcl_Preserve\fR for the object has been
 300 matched by calls to \fBTcl_Release\fR.
 301 There may be any number of unmatched \fBTcl_Preserve\fR calls
 302 in effect at once.
 303 .PP
 304 \fBTcl_EventuallyFree\fR is invoked to free up its \fIclientData\fR
 305 argument.
 306 It checks to see if there are unmatched \fBTcl_Preserve\fR calls
 307 for the object.
 308 If not, then \fBTcl_EventuallyFree\fR calls \fIfreeProc\fR immediately.
 309 Otherwise \fBTcl_EventuallyFree\fR records the fact that \fIclientData\fR
 310 needs eventually to be freed.
 311 When all calls to \fBTcl_Preserve\fR have been matched with
 312 calls to \fBTcl_Release\fR then \fIfreeProc\fR will be called by
 313 \fBTcl_Release\fR to do the cleanup.
 314 .PP
 315 All the work of freeing the object is carried out by \fIfreeProc\fR.
 316 \fIFreeProc\fR must have arguments and result that match the
 317 type \fBTcl_FreeProc\fR:
 318 .CS
 319 typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
 320 .CE
 321 The \fIblockPtr\fR argument to \fIfreeProc\fR will be the
 322 same as the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR.
 323 The type of \fIblockPtr\fR (\fBchar *\fR) is different than the type of the
 324 \fIclientData\fR argument to \fBTcl_EventuallyFree\fR for historical
 325 reasons, but the value is the same.
 326 .PP
 327 This mechanism can be used to solve the problem described above
 328 by placing \fBTcl_Preserve\fR and \fBTcl_Release\fR calls around
 329 actions that may cause undesired storage re-allocation.  The
 330 mechanism is intended only for short-term use (i.e. while procedures
 331 are pending on the stack);  it will not work efficiently as a
 332 mechanism for long-term reference counts.
 333 The implementation does not depend in any way on the internal
 334 structure of the objects being freed;  it keeps the reference
 335 counts in a separate structure.
 336
 337 .SH KEYWORDS
 338 free, reference count, storage