1Tcl_Obj(3) Tcl Library Procedures Tcl_Obj(3)
2______________________________________________________________________________
6
8 Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount,
9 Tcl_IsShared, Tcl_InvalidateStringRep - manipulate Tcl values
10
12 #include <tcl.h>
13 Tcl_Obj *
15 Tcl_NewObj()
16 Tcl_Obj *
18 Tcl_DuplicateObj(objPtr)
19 Tcl_IncrRefCount(objPtr)
21 Tcl_DecrRefCount(objPtr)
23 int
25 Tcl_IsShared(objPtr)
26 Tcl_InvalidateStringRep(objPtr)
28
30 Tcl_Obj *objPtr (in) Points to a value; must have been the
31 result of a previous call to Tcl_NewObj.
32______________________________________________________________________________
33
35 This man page presents an overview of Tcl values (called Tcl_Objs for
36 historical reasons) and how they are used. It also describes generic
37 procedures for managing Tcl values. These procedures are used to cre‐
38 ate and copy values, and increment and decrement the count of refer‐
39 ences (pointers) to values. The procedures are used in conjunction
40 with ones that operate on specific types of values such as Tcl_GetInt‐
41 FromObj and Tcl_ListObjAppendElement. The individual procedures are
42 described along with the data structures they manipulate.
43 Tcl's dual-ported values provide a general-purpose mechanism for stor‐
45 ing and exchanging Tcl values. They largely replace the use of strings
46 in Tcl. For example, they are used to store variable values, command
47 arguments, command results, and scripts. Tcl values behave like
48 strings but also hold an internal representation that can be manipu‐
49 lated more efficiently. For example, a Tcl list is now represented as
50 a value that holds the list's string representation as well as an array
51 of pointers to the values for each list element. Dual-ported values
52 avoid most runtime type conversions. They also improve the speed of
53 many operations since an appropriate representation is immediately
54 available. The compiler itself uses Tcl values to cache the instruc‐
55 tion bytecodes resulting from compiling scripts.
56 The two representations are a cache of each other and are computed
58 lazily. That is, each representation is only computed when necessary,
59 it is computed from the other representation, and, once computed, it is
60 saved. In addition, a change in one representation invalidates the
61 other one. As an example, a Tcl program doing integer calculations can
62 operate directly on a variable's internal machine integer representa‐
63 tion without having to constantly convert between integers and strings.
64 Only when it needs a string representing the variable's value, say to
65 print it, will the program regenerate the string representation from
66 the integer. Although values contain an internal representation, their
67 semantics are defined in terms of strings: an up-to-date string can
68 always be obtained, and any change to the value will be reflected in
69 that string when the value's string representation is fetched. Because
70 of this representation invalidation and regeneration, it is dangerous
71 for extension writers to access Tcl_Obj fields directly. It is better
72 to access Tcl_Obj information using procedures like Tcl_GetStringFro‐
73 mObj and Tcl_GetString.
74 Values are allocated on the heap and are referenced using a pointer to
76 their Tcl_Obj structure. Values are shared as much as possible. This
77 significantly reduces storage requirements because some values such as
78 long lists are very large. Also, most Tcl values are only read and
79 never modified. This is especially true for procedure arguments, which
80 can be shared between the caller and the called procedure. Assignment
81 and argument binding is done by simply assigning a pointer to the
82 value. Reference counting is used to determine when it is safe to
83 reclaim a value's storage.
84 Tcl values are typed. A value's internal representation is controlled
86 by its type. Several types are predefined in the Tcl core including
87 integer, double, list, and bytecode. Extension writers can extend the
88 set of types by defining their own Tcl_ObjType structs.
89
91 Each Tcl value is represented by a Tcl_Obj structure which is defined
92 as follows.
93 typedef struct Tcl_Obj {
95 int refCount;
96 char *bytes;
97 int length;
98 const Tcl_ObjType *typePtr;
99 union {
100 long longValue;
101 double doubleValue;
102 void *otherValuePtr;
103 Tcl_WideInt wideValue;
104 struct {
105 void *ptr1;
106 void *ptr2;
107 } twoPtrValue;
108 struct {
109 void *ptr;
110 unsigned long value;
111 } ptrAndLongRep;
112 } internalRep;
113 } Tcl_Obj;
114 The bytes and the length members together hold a value's UTF-8 string
116 representation, which is a counted string not containing null bytes
117 (UTF-8 null characters should be encoded as a two byte sequence: 192,
118 128.) bytes points to the first byte of the string representation.
119 The length member gives the number of bytes. The byte array must
120 always have a null byte after the last data byte, at offset length;
121 this allows string representations to be treated as conventional null-
122 terminated C strings. C programs use Tcl_GetStringFromObj and Tcl_Get‐
123 String to get a value's string representation. If bytes is NULL, the
124 string representation is invalid.
125 A value's type manages its internal representation. The member typePtr
127 points to the Tcl_ObjType structure that describes the type. If type‐
128 Ptr is NULL, the internal representation is invalid.
129 The internalRep union member holds a value's internal representation.
131 This is either a (long) integer, a double-precision floating-point num‐
132 ber, a pointer to a value containing additional information needed by
133 the value's type to represent the value, a Tcl_WideInt integer, two
134 arbitrary pointers, or a pair made up of an unsigned long integer and a
135 pointer.
136 The refCount member is used to tell when it is safe to free a value's
138 storage. It holds the count of active references to the value. Main‐
139 taining the correct reference count is a key responsibility of exten‐
140 sion writers. Reference counting is discussed below in the section
141 STORAGE MANAGEMENT OF VALUES.
142 Although extension writers can directly access the members of a Tcl_Obj
144 structure, it is much better to use the appropriate procedures and
145 macros. For example, extension writers should never read or update
146 refCount directly; they should use macros such as Tcl_IncrRefCount and
147 Tcl_IsShared instead.
148 A key property of Tcl values is that they hold two representations. A
150 value typically starts out containing only a string representation: it
151 is untyped and has a NULL typePtr. A value containing an empty string
152 or a copy of a specified string is created using Tcl_NewObj or Tcl_New‐
153 StringObj respectively. A value's string value is gotten with Tcl_Get‐
154 StringFromObj or Tcl_GetString and changed with Tcl_SetStringObj. If
155 the value is later passed to a procedure like Tcl_GetIntFromObj that
156 requires a specific internal representation, the procedure will create
157 one and set the value's typePtr. The internal representation is com‐
158 puted from the string representation. A value's two representations
159 are duals of each other: changes made to one are reflected in the
160 other. For example, Tcl_ListObjReplace will modify a value's internal
161 representation and the next call to Tcl_GetStringFromObj or Tcl_Get‐
162 String will reflect that change.
163 Representations are recomputed lazily for efficiency. A change to one
165 representation made by a procedure such as Tcl_ListObjReplace is not
166 reflected immediately in the other representation. Instead, the other
167 representation is marked invalid so that it is only regenerated if it
168 is needed later. Most C programmers never have to be concerned with
169 how this is done and simply use procedures such as Tcl_GetBooleanFro‐
170 mObj or Tcl_ListObjIndex. Programmers that implement their own value
171 types must check for invalid representations and mark representations
172 invalid when necessary. The procedure Tcl_InvalidateStringRep is used
173 to mark a value's string representation invalid and to free any storage
174 associated with the old string representation.
175 Values usually remain one type over their life, but occasionally a
177 value must be converted from one type to another. For example, a C
178 program might build up a string in a value with repeated calls to
179 Tcl_AppendToObj, and then call Tcl_ListObjIndex to extract a list ele‐
180 ment from the value. The same value holding the same string value can
181 have several different internal representations at different times.
182 Extension writers can also force a value to be converted from one type
183 to another using the Tcl_ConvertToType procedure. Only programmers
184 that create new value types need to be concerned about how this is
185 done. A procedure defined as part of the value type's implementation
186 creates a new internal representation for a value and changes its type‐
187 Ptr. See the man page for Tcl_RegisterObjType to see how to create a
188 new value type.
189
191 As an example of the lifetime of a value, consider the following
192 sequence of commands:
193 set x 123
195 This assigns to x an untyped value whose bytes member points to 123 and
197 length member contains 3. The value's typePtr member is NULL.
198 puts "x is $x"
200 x's string representation is valid (since bytes is non-NULL) and is
202 fetched for the command.
203 incr x
205 The incr command first gets an integer from x's value by calling
207 Tcl_GetIntFromObj. This procedure checks whether the value is already
208 an integer value. Since it is not, it converts the value by setting
209 the value's internal representation to the integer 123 and setting the
210 value's typePtr to point to the integer Tcl_ObjType structure. Both
211 representations are now valid. incr increments the value's integer
212 internal representation then invalidates its string representation (by
213 calling Tcl_InvalidateStringRep) since the string representation no
214 longer corresponds to the internal representation.
215 puts "x is now $x"
217 The string representation of x's value is needed and is recomputed.
219 The string representation is now 124 and both representations are again
220 valid.
221
223 Tcl values are allocated on the heap and are shared as much as possible
224 to reduce storage requirements. Reference counting is used to deter‐
225 mine when a value is no longer needed and can safely be freed. A value
226 just created by Tcl_NewObj or Tcl_NewStringObj has refCount 0. The
227 macro Tcl_IncrRefCount increments the reference count when a new refer‐
228 ence to the value is created. The macro Tcl_DecrRefCount decrements
229 the count when a reference is no longer needed and, if the value's ref‐
230 erence count drops to zero, frees its storage. A value shared by dif‐
231 ferent code or data structures has refCount greater than 1. Increment‐
232 ing a value's reference count ensures that it will not be freed too
233 early or have its value change accidentally.
234 As an example, the bytecode interpreter shares argument values between
236 calling and called Tcl procedures to avoid having to copy values. It
237 assigns the call's argument values to the procedure's formal parameter
238 variables. In doing so, it calls Tcl_IncrRefCount to increment the
239 reference count of each argument since there is now a new reference to
240 it from the formal parameter. When the called procedure returns, the
241 interpreter calls Tcl_DecrRefCount to decrement each argument's refer‐
242 ence count. When a value's reference count drops less than or equal to
243 zero, Tcl_DecrRefCount reclaims its storage. Most command procedures
244 do not have to be concerned about reference counting since they use a
245 value's value immediately and do not retain a pointer to the value
246 after they return. However, if they do retain a pointer to a value in
247 a data structure, they must be careful to increment its reference count
248 since the retained pointer is a new reference.
249 Command procedures that directly modify values such as those for lap‐
251 pend and linsert must be careful to copy a shared value before changing
252 it. They must first check whether the value is shared by calling
253 Tcl_IsShared. If the value is shared they must copy the value by using
254 Tcl_DuplicateObj; this returns a new duplicate of the original value
255 that has refCount 0. If the value is not shared, the command procedure
256 “owns” the value and can safely modify it directly. For example, the
257 following code appears in the command procedure that implements lin‐
258 sert. This procedure modifies the list value passed to it in objv[1]
259 by inserting objc-3 new elements before index.
260 listPtr = objv[1];
262 if (Tcl_IsShared(listPtr)) {
263 listPtr = Tcl_DuplicateObj(listPtr);
264 }
265 result = Tcl_ListObjReplace(interp, listPtr, index, 0,
266 (objc-3), &(objv[3]));
267 As another example, incr's command procedure must check whether the
269 variable's value is shared before incrementing the integer in its
270 internal representation. If it is shared, it needs to duplicate the
271 value in order to avoid accidentally changing values in other data
272 structures.
273
275 Tcl_ConvertToType(3), Tcl_GetIntFromObj(3), Tcl_ListObjAppendEle‐
276 ment(3), Tcl_ListObjIndex(3), Tcl_ListObjReplace(3), Tcl_RegisterObj‐
277 Type(3)
278
280 internal representation, value, value creation, value type, reference
281 counting, string representation, type conversion
282Tcl 8.5 Tcl_Obj(3)