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