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