Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | '\" |
2 | '\" Copyright (c) 1996-1997 Sun Microsystems, Inc. | |
3 | '\" | |
4 | '\" See the file "license.terms" for information on usage and redistribution | |
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
6 | '\" | |
7 | '\" RCS: @(#) $Id: Object.3,v 1.6 2002/10/22 12:16:53 dkf Exp $ | |
8 | '\" | |
9 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
10 | '\" manual entries. | |
11 | '\" | |
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) | |
18 | '\" | |
19 | '\" .AS ?type? ?name? | |
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. | |
23 | '\" | |
24 | '\" .BS | |
25 | '\" Start box enclosure. From here until next .BE, everything will be | |
26 | '\" enclosed in one large box. | |
27 | '\" | |
28 | '\" .BE | |
29 | '\" End of box enclosure. | |
30 | '\" | |
31 | '\" .CS | |
32 | '\" Begin code excerpt. | |
33 | '\" | |
34 | '\" .CE | |
35 | '\" End code excerpt. | |
36 | '\" | |
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. | |
43 | '\" | |
44 | '\" .VE | |
45 | '\" End of vertical sidebar. | |
46 | '\" | |
47 | '\" .DS | |
48 | '\" Begin an indented unfilled display. | |
49 | '\" | |
50 | '\" .DE | |
51 | '\" End of indented unfilled display. | |
52 | '\" | |
53 | '\" .SO | |
54 | '\" Start of list of standard options for a Tk widget. The | |
55 | '\" options follow on successive lines, in four columns separated | |
56 | '\" by tabs. | |
57 | '\" | |
58 | '\" .SE | |
59 | '\" End of list of standard options for a Tk widget. | |
60 | '\" | |
61 | '\" .OP cmdName dbName dbClass | |
62 | '\" Start of description of a specific option. cmdName gives the | |
63 | '\" option's name as specified in the class command, dbName gives | |
64 | '\" the option's name in the option database, and dbClass gives | |
65 | '\" the option's class in the option database. | |
66 | '\" | |
67 | '\" .UL arg1 arg2 | |
68 | '\" Print arg1 underlined, then print arg2 normally. | |
69 | '\" | |
70 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
71 | '\" | |
72 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
73 | .if t .wh -1.3i ^B | |
74 | .nr ^l \n(.l | |
75 | .ad b | |
76 | '\" # Start an argument description | |
77 | .de AP | |
78 | .ie !"\\$4"" .TP \\$4 | |
79 | .el \{\ | |
80 | . ie !"\\$2"" .TP \\n()Cu | |
81 | . el .TP 15 | |
82 | .\} | |
83 | .ta \\n()Au \\n()Bu | |
84 | .ie !"\\$3"" \{\ | |
85 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
86 | .\".b | |
87 | .\} | |
88 | .el \{\ | |
89 | .br | |
90 | .ie !"\\$2"" \{\ | |
91 | \&\\$1 \\fI\\$2\\fP | |
92 | .\} | |
93 | .el \{\ | |
94 | \&\\fI\\$1\\fP | |
95 | .\} | |
96 | .\} | |
97 | .. | |
98 | '\" # define tabbing values for .AP | |
99 | .de AS | |
100 | .nr )A 10n | |
101 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
102 | .nr )B \\n()Au+15n | |
103 | .\" | |
104 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
105 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
106 | .. | |
107 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
108 | '\" # BS - start boxed text | |
109 | '\" # ^y = starting y location | |
110 | '\" # ^b = 1 | |
111 | .de BS | |
112 | .br | |
113 | .mk ^y | |
114 | .nr ^b 1u | |
115 | .if n .nf | |
116 | .if n .ti 0 | |
117 | .if n \l'\\n(.lu\(ul' | |
118 | .if n .fi | |
119 | .. | |
120 | '\" # BE - end boxed text (draw box now) | |
121 | .de BE | |
122 | .nf | |
123 | .ti 0 | |
124 | .mk ^t | |
125 | .ie n \l'\\n(^lu\(ul' | |
126 | .el \{\ | |
127 | .\" Draw four-sided box normally, but don't draw top of | |
128 | .\" box if the box started on an earlier page. | |
129 | .ie !\\n(^b-1 \{\ | |
130 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
131 | .\} | |
132 | .el \}\ | |
133 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
134 | .\} | |
135 | .\} | |
136 | .fi | |
137 | .br | |
138 | .nr ^b 0 | |
139 | .. | |
140 | '\" # VS - start vertical sidebar | |
141 | '\" # ^Y = starting y location | |
142 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
143 | .de VS | |
144 | .if !"\\$2"" .br | |
145 | .mk ^Y | |
146 | .ie n 'mc \s12\(br\s0 | |
147 | .el .nr ^v 1u | |
148 | .. | |
149 | '\" # VE - end of vertical sidebar | |
150 | .de VE | |
151 | .ie n 'mc | |
152 | .el \{\ | |
153 | .ev 2 | |
154 | .nf | |
155 | .ti 0 | |
156 | .mk ^t | |
157 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
158 | .sp -1 | |
159 | .fi | |
160 | .ev | |
161 | .\} | |
162 | .nr ^v 0 | |
163 | .. | |
164 | '\" # Special macro to handle page bottom: finish off current | |
165 | '\" # box/sidebar if in box/sidebar mode, then invoked standard | |
166 | '\" # page bottom macro. | |
167 | .de ^B | |
168 | .ev 2 | |
169 | 'ti 0 | |
170 | 'nf | |
171 | .mk ^t | |
172 | .if \\n(^b \{\ | |
173 | .\" Draw three-sided box if this is the box's first page, | |
174 | .\" draw two sides but no top otherwise. | |
175 | .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 | |
176 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
177 | .\} | |
178 | .if \\n(^v \{\ | |
179 | .nr ^x \\n(^tu+1v-\\n(^Yu | |
180 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c | |
181 | .\} | |
182 | .bp | |
183 | 'fi | |
184 | .ev | |
185 | .if \\n(^b \{\ | |
186 | .mk ^y | |
187 | .nr ^b 2 | |
188 | .\} | |
189 | .if \\n(^v \{\ | |
190 | .mk ^Y | |
191 | .\} | |
192 | .. | |
193 | '\" # DS - begin display | |
194 | .de DS | |
195 | .RS | |
196 | .nf | |
197 | .sp | |
198 | .. | |
199 | '\" # DE - end display | |
200 | .de DE | |
201 | .fi | |
202 | .RE | |
203 | .sp | |
204 | .. | |
205 | '\" # SO - start of list of standard options | |
206 | .de SO | |
207 | .SH "STANDARD OPTIONS" | |
208 | .LP | |
209 | .nf | |
210 | .ta 5.5c 11c | |
211 | .ft B | |
212 | .. | |
213 | '\" # SE - end of list of standard options | |
214 | .de SE | |
215 | .fi | |
216 | .ft R | |
217 | .LP | |
218 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
219 | .. | |
220 | '\" # OP - start of full description for a single option | |
221 | .de OP | |
222 | .LP | |
223 | .nf | |
224 | .ta 4c | |
225 | Command-Line Name: \\fB\\$1\\fR | |
226 | Database Name: \\fB\\$2\\fR | |
227 | Database Class: \\fB\\$3\\fR | |
228 | .fi | |
229 | .IP | |
230 | .. | |
231 | '\" # CS - begin code excerpt | |
232 | .de CS | |
233 | .RS | |
234 | .nf | |
235 | .ta .25i .5i .75i 1i | |
236 | .. | |
237 | '\" # CE - end code excerpt | |
238 | .de CE | |
239 | .fi | |
240 | .RE | |
241 | .. | |
242 | .de UL | |
243 | \\$1\l'|0\(ul'\\$2 | |
244 | .. | |
245 | .TH Tcl_Obj 3 8.1 Tcl "Tcl Library Procedures" | |
246 | .BS | |
247 | .SH NAME | |
248 | Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_InvalidateStringRep \- manipulate Tcl objects | |
249 | .SH SYNOPSIS | |
250 | .nf | |
251 | \fB#include <tcl.h>\fR | |
252 | .sp | |
253 | Tcl_Obj * | |
254 | \fBTcl_NewObj\fR() | |
255 | .sp | |
256 | Tcl_Obj * | |
257 | \fBTcl_DuplicateObj\fR(\fIobjPtr\fR) | |
258 | .sp | |
259 | \fBTcl_IncrRefCount\fR(\fIobjPtr\fR) | |
260 | .sp | |
261 | \fBTcl_DecrRefCount\fR(\fIobjPtr\fR) | |
262 | .sp | |
263 | int | |
264 | \fBTcl_IsShared\fR(\fIobjPtr\fR) | |
265 | .sp | |
266 | \fBTcl_InvalidateStringRep\fR(\fIobjPtr\fR) | |
267 | .SH ARGUMENTS | |
268 | .AS Tcl_Obj *objPtr in | |
269 | .AP Tcl_Obj *objPtr in | |
270 | Points to an object; | |
271 | must have been the result of a previous call to \fBTcl_NewObj\fR. | |
272 | .BE | |
273 | ||
274 | .SH INTRODUCTION | |
275 | .PP | |
276 | This man page presents an overview of Tcl objects and how they are used. | |
277 | It also describes generic procedures for managing Tcl objects. | |
278 | These procedures are used to create and copy objects, | |
279 | and increment and decrement the count of references (pointers) to objects. | |
280 | The procedures are used in conjunction with ones | |
281 | that operate on specific types of objects such as | |
282 | \fBTcl_GetIntFromObj\fR and \fBTcl_ListObjAppendElement\fR. | |
283 | The individual procedures are described along with the data structures | |
284 | they manipulate. | |
285 | .PP | |
286 | Tcl's \fIdual-ported\fR objects provide a general-purpose mechanism | |
287 | for storing and exchanging Tcl values. | |
288 | They largely replace the use of strings in Tcl. | |
289 | For example, they are used to store variable values, | |
290 | command arguments, command results, and scripts. | |
291 | Tcl objects behave like strings but also hold an internal representation | |
292 | that can be manipulated more efficiently. | |
293 | For example, a Tcl list is now represented as an object | |
294 | that holds the list's string representation | |
295 | as well as an array of pointers to the objects for each list element. | |
296 | Dual-ported objects avoid most runtime type conversions. | |
297 | They also improve the speed of many operations | |
298 | since an appropriate representation is immediately available. | |
299 | The compiler itself uses Tcl objects to | |
300 | cache the instruction bytecodes resulting from compiling scripts. | |
301 | .PP | |
302 | The two representations are a cache of each other and are computed lazily. | |
303 | That is, each representation is only computed when necessary, | |
304 | it is computed from the other representation, | |
305 | and, once computed, it is saved. | |
306 | In addition, a change in one representation invalidates the other one. | |
307 | As an example, a Tcl program doing integer calculations can | |
308 | operate directly on a variable's internal machine integer | |
309 | representation without having to constantly convert | |
310 | between integers and strings. | |
311 | Only when it needs a string representing the variable's value, | |
312 | say to print it, | |
313 | will the program regenerate the string representation from the integer. | |
314 | Although objects contain an internal representation, | |
315 | their semantics are defined in terms of strings: | |
316 | an up-to-date string can always be obtained, | |
317 | and any change to the object will be reflected in that string | |
318 | when the object's string representation is fetched. | |
319 | Because of this representation invalidation and regeneration, | |
320 | it is dangerous for extension writers to access | |
321 | \fBTcl_Obj\fR fields directly. | |
322 | It is better to access Tcl_Obj information using | |
323 | procedures like \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR. | |
324 | .PP | |
325 | Objects are allocated on the heap | |
326 | and are referenced using a pointer to their \fBTcl_Obj\fR structure. | |
327 | Objects are shared as much as possible. | |
328 | This significantly reduces storage requirements | |
329 | because some objects such as long lists are very large. | |
330 | Also, most Tcl values are only read and never modified. | |
331 | This is especially true for procedure arguments, | |
332 | which can be shared between the caller and the called procedure. | |
333 | Assignment and argument binding is done by | |
334 | simply assigning a pointer to the value. | |
335 | Reference counting is used to determine when it is safe to | |
336 | reclaim an object's storage. | |
337 | .PP | |
338 | Tcl objects are typed. | |
339 | An object's internal representation is controlled by its type. | |
340 | Seven types are predefined in the Tcl core | |
341 | including integer, double, list, and bytecode. | |
342 | Extension writers can extend the set of types | |
343 | by using the procedure \fBTcl_RegisterObjType\fR . | |
344 | ||
345 | .SH "THE TCL_OBJ STRUCTURE" | |
346 | .PP | |
347 | Each Tcl object is represented by a \fBTcl_Obj\fR structure | |
348 | which is defined as follows. | |
349 | .CS | |
350 | typedef struct Tcl_Obj { | |
351 | int \fIrefCount\fR; | |
352 | char *\fIbytes\fR; | |
353 | int \fIlength\fR; | |
354 | Tcl_ObjType *\fItypePtr\fR; | |
355 | union { | |
356 | long \fIlongValue\fR; | |
357 | double \fIdoubleValue\fR; | |
358 | VOID *\fIotherValuePtr\fR; | |
359 | struct { | |
360 | VOID *\fIptr1\fR; | |
361 | VOID *\fIptr2\fR; | |
362 | } \fItwoPtrValue\fR; | |
363 | } \fIinternalRep\fR; | |
364 | } Tcl_Obj; | |
365 | .CE | |
366 | The \fIbytes\fR and the \fIlength\fR members together hold | |
367 | .VS 8.1 | |
368 | an object's UTF-8 string representation, | |
369 | which is a \fIcounted string\fR not containing null bytes (UTF-8 null | |
370 | characters should be encoded as a two byte sequence: 192, 128.) | |
371 | \fIbytes\fR points to the first byte of the string representation. | |
372 | The \fIlength\fR member gives the number of bytes. | |
373 | The byte array must always have a null byte after the last data byte, | |
374 | at offset \fIlength\fR; | |
375 | this allows string representations | |
376 | to be treated as conventional null-terminated C strings. | |
377 | .VE 8.1 | |
378 | C programs use \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR to get | |
379 | an object's string representation. | |
380 | If \fIbytes\fR is NULL, | |
381 | the string representation is invalid. | |
382 | .PP | |
383 | An object's type manages its internal representation. | |
384 | The member \fItypePtr\fR points to the Tcl_ObjType structure | |
385 | that describes the type. | |
386 | If \fItypePtr\fR is NULL, | |
387 | the internal representation is invalid. | |
388 | .PP | |
389 | The \fIinternalRep\fR union member holds | |
390 | an object's internal representation. | |
391 | This is either a (long) integer, a double-precision floating point number, | |
392 | a pointer to a value containing additional information | |
393 | needed by the object's type to represent the object, | |
394 | or two arbitrary pointers. | |
395 | .PP | |
396 | The \fIrefCount\fR member is used to tell when it is safe to free | |
397 | an object's storage. | |
398 | It holds the count of active references to the object. | |
399 | Maintaining the correct reference count is a key responsibility | |
400 | of extension writers. | |
401 | Reference counting is discussed below | |
402 | in the section \fBSTORAGE MANAGEMENT OF OBJECTS\fR. | |
403 | .PP | |
404 | Although extension writers can directly access | |
405 | the members of a Tcl_Obj structure, | |
406 | it is much better to use the appropriate procedures and macros. | |
407 | For example, extension writers should never | |
408 | read or update \fIrefCount\fR directly; | |
409 | they should use macros such as | |
410 | \fBTcl_IncrRefCount\fR and \fBTcl_IsShared\fR instead. | |
411 | .PP | |
412 | A key property of Tcl objects is that they hold two representations. | |
413 | An object typically starts out containing only a string representation: | |
414 | it is untyped and has a NULL \fItypePtr\fR. | |
415 | An object containing an empty string or a copy of a specified string | |
416 | is created using \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR respectively. | |
417 | An object's string value is gotten with | |
418 | \fBTcl_GetStringFromObj\fR or \fBTcl_GetString\fR | |
419 | and changed with \fBTcl_SetStringObj\fR. | |
420 | If the object is later passed to a procedure like \fBTcl_GetIntFromObj\fR | |
421 | that requires a specific internal representation, | |
422 | the procedure will create one and set the object's \fItypePtr\fR. | |
423 | The internal representation is computed from the string representation. | |
424 | An object's two representations are duals of each other: | |
425 | changes made to one are reflected in the other. | |
426 | For example, \fBTcl_ListObjReplace\fR will modify an object's | |
427 | internal representation and the next call to \fBTcl_GetStringFromObj\fR | |
428 | or \fBTcl_GetString\fR will reflect that change. | |
429 | .PP | |
430 | Representations are recomputed lazily for efficiency. | |
431 | A change to one representation made by a procedure | |
432 | such as \fBTcl_ListObjReplace\fR is not reflected immediately | |
433 | in the other representation. | |
434 | Instead, the other representation is marked invalid | |
435 | so that it is only regenerated if it is needed later. | |
436 | Most C programmers never have to be concerned with how this is done | |
437 | and simply use procedures such as \fBTcl_GetBooleanFromObj\fR or | |
438 | \fBTcl_ListObjIndex\fR. | |
439 | Programmers that implement their own object types | |
440 | must check for invalid representations | |
441 | and mark representations invalid when necessary. | |
442 | The procedure \fBTcl_InvalidateStringRep\fR is used | |
443 | to mark an object's string representation invalid and to | |
444 | free any storage associated with the old string representation. | |
445 | .PP | |
446 | Objects usually remain one type over their life, | |
447 | but occasionally an object must be converted from one type to another. | |
448 | For example, a C program might build up a string in an object | |
449 | with repeated calls to \fBTcl_AppendToObj\fR, | |
450 | and then call \fBTcl_ListObjIndex\fR to extract a list element from | |
451 | the object. | |
452 | The same object holding the same string value | |
453 | can have several different internal representations | |
454 | at different times. | |
455 | Extension writers can also force an object to be converted from one type | |
456 | to another using the \fBTcl_ConvertToType\fR procedure. | |
457 | Only programmers that create new object types need to be concerned | |
458 | about how this is done. | |
459 | A procedure defined as part of the object type's implementation | |
460 | creates a new internal representation for an object | |
461 | and changes its \fItypePtr\fR. | |
462 | See the man page for \fBTcl_RegisterObjType\fR | |
463 | to see how to create a new object type. | |
464 | ||
465 | .SH "EXAMPLE OF THE LIFETIME OF AN OBJECT" | |
466 | .PP | |
467 | As an example of the lifetime of an object, | |
468 | consider the following sequence of commands: | |
469 | .CS | |
470 | \fBset x 123\fR | |
471 | .CE | |
472 | This assigns to \fIx\fR an untyped object whose | |
473 | \fIbytes\fR member points to \fB123\fR and \fIlength\fR member contains 3. | |
474 | The object's \fItypePtr\fR member is NULL. | |
475 | .CS | |
476 | \fBputs "x is $x"\fR | |
477 | .CE | |
478 | \fIx\fR's string representation is valid (since \fIbytes\fR is non-NULL) | |
479 | and is fetched for the command. | |
480 | .CS | |
481 | \fBincr x\fR | |
482 | .CE | |
483 | The \fBincr\fR command first gets an integer from \fIx\fR's object | |
484 | by calling \fBTcl_GetIntFromObj\fR. | |
485 | This procedure checks whether the object is already an integer object. | |
486 | Since it is not, it converts the object | |
487 | by setting the object's \fIinternalRep.longValue\fR member | |
488 | to the integer \fB123\fR | |
489 | and setting the object's \fItypePtr\fR | |
490 | to point to the integer Tcl_ObjType structure. | |
491 | Both representations are now valid. | |
492 | \fBincr\fR increments the object's integer internal representation | |
493 | then invalidates its string representation | |
494 | (by calling \fBTcl_InvalidateStringRep\fR) | |
495 | since the string representation | |
496 | no longer corresponds to the internal representation. | |
497 | .CS | |
498 | \fBputs "x is now $x"\fR | |
499 | .CE | |
500 | The string representation of \fIx\fR's object is needed | |
501 | and is recomputed. | |
502 | The string representation is now \fB124\fR. | |
503 | and both representations are again valid. | |
504 | ||
505 | .SH "STORAGE MANAGEMENT OF OBJECTS" | |
506 | .PP | |
507 | Tcl objects are allocated on the heap and are shared as much as possible | |
508 | to reduce storage requirements. | |
509 | Reference counting is used to determine when an object is | |
510 | no longer needed and can safely be freed. | |
511 | An object just created by \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR | |
512 | has \fIrefCount\fR 0. | |
513 | The macro \fBTcl_IncrRefCount\fR increments the reference count | |
514 | when a new reference to the object is created. | |
515 | The macro \fBTcl_DecrRefCount\fR decrements the count | |
516 | when a reference is no longer needed and, | |
517 | if the object's reference count drops to zero, frees its storage. | |
518 | An object shared by different code or data structures has | |
519 | \fIrefCount\fR greater than 1. | |
520 | Incrementing an object's reference count ensures that | |
521 | it won't be freed too early or have its value change accidently. | |
522 | .PP | |
523 | As an example, the bytecode interpreter shares argument objects | |
524 | between calling and called Tcl procedures to avoid having to copy objects. | |
525 | It assigns the call's argument objects to the procedure's | |
526 | formal parameter variables. | |
527 | In doing so, it calls \fBTcl_IncrRefCount\fR to increment | |
528 | the reference count of each argument since there is now a new | |
529 | reference to it from the formal parameter. | |
530 | When the called procedure returns, | |
531 | the interpreter calls \fBTcl_DecrRefCount\fR to decrement | |
532 | each argument's reference count. | |
533 | When an object's reference count drops less than or equal to zero, | |
534 | \fBTcl_DecrRefCount\fR reclaims its storage. | |
535 | Most command procedures do not have to be concerned about | |
536 | reference counting since they use an object's value immediately | |
537 | and don't retain a pointer to the object after they return. | |
538 | However, if they do retain a pointer to an object in a data structure, | |
539 | they must be careful to increment its reference count | |
540 | since the retained pointer is a new reference. | |
541 | .PP | |
542 | Command procedures that directly modify objects | |
543 | such as those for \fBlappend\fR and \fBlinsert\fR must be careful to | |
544 | copy a shared object before changing it. | |
545 | They must first check whether the object is shared | |
546 | by calling \fBTcl_IsShared\fR. | |
547 | If the object is shared they must copy the object | |
548 | by using \fBTcl_DuplicateObj\fR; | |
549 | this returns a new duplicate of the original object | |
550 | that has \fIrefCount\fR 0. | |
551 | If the object is not shared, | |
552 | the command procedure "owns" the object and can safely modify it directly. | |
553 | For example, the following code appears in the command procedure | |
554 | that implements \fBlinsert\fR. | |
555 | This procedure modifies the list object passed to it in \fIobjv[1]\fR | |
556 | by inserting \fIobjc-3\fR new elements before \fIindex\fR. | |
557 | .CS | |
558 | listPtr = objv[1]; | |
559 | if (Tcl_IsShared(listPtr)) { | |
560 | listPtr = Tcl_DuplicateObj(listPtr); | |
561 | } | |
562 | result = Tcl_ListObjReplace(interp, listPtr, index, 0, (objc-3), &(objv[3])); | |
563 | .CE | |
564 | As another example, \fBincr\fR's command procedure | |
565 | must check whether the variable's object is shared before | |
566 | incrementing the integer in its internal representation. | |
567 | If it is shared, it needs to duplicate the object | |
568 | in order to avoid accidently changing values in other data structures. | |
569 | ||
570 | .SH "SEE ALSO" | |
571 | Tcl_ConvertToType, Tcl_GetIntFromObj, Tcl_ListObjAppendElement, Tcl_ListObjIndex, Tcl_ListObjReplace, Tcl_RegisterObjType | |
572 | ||
573 | .SH KEYWORDS | |
574 | internal representation, object, object creation, object type, reference counting, string representation, type conversion |