1Tcl_Obj(3)                  Tcl Library Procedures                  Tcl_Obj(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_NewObj,   Tcl_DuplicateObj,   Tcl_IncrRefCount,   Tcl_DecrRefCount,
9       Tcl_IsShared, Tcl_InvalidateStringRep - manipulate Tcl objects
10

SYNOPSIS

12       #include <tcl.h>
13
14       Tcl_Obj *
15       Tcl_NewObj()
16
17       Tcl_Obj *
18       Tcl_DuplicateObj(objPtr)
19
20       Tcl_IncrRefCount(objPtr)
21
22       Tcl_DecrRefCount(objPtr)
23
24       int
25       Tcl_IsShared(objPtr)
26
27       Tcl_InvalidateStringRep(objPtr)
28

ARGUMENTS

30       Tcl_Obj   *objPtr   (in)      Points to an object; must have  been  the
31                                     result of a previous call to Tcl_NewObj.
32_________________________________________________________________
33
34

INTRODUCTION

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
45       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
58       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
76       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
86       Tcl  objects  are  typed.   An object's internal representation is con‐
87       trolled by its type.  Seven  types  are  predefined  in  the  Tcl  core
88       including  integer,  double, list, and bytecode.  Extension writers can
89       extend the set of types by using the procedure Tcl_RegisterObjType .
90
91

THE TCL_OBJ STRUCTURE

93       Each Tcl object is represented by a Tcl_Obj structure which is  defined
94       as follows.
95              typedef struct Tcl_Obj {
96                int refCount;
97                char *bytes;
98                int length;
99                Tcl_ObjType *typePtr;
100                union {
101                   long longValue;
102                   double doubleValue;
103                   VOID *otherValuePtr;
104                   struct {
105                     VOID *ptr1;
106                     VOID *ptr2;
107                   } twoPtrValue;
108                } internalRep;
109              } Tcl_Obj;
110       The bytes and the length members together hold an object's UTF-8 string │
111       representation, which is a counted string  not  containing  null  bytes │
112       (UTF-8  null  characters should be encoded as a two byte sequence: 192, │
113       128.)  bytes points to the first byte  of  the  string  representation. │
114       The  length  member  gives  the  number  of bytes.  The byte array must │
115       always have a null byte after the last data  byte,  at  offset  length; │
116       this  allows string representations to be treated as conventional null- │
117       terminated C strings.  C programs use Tcl_GetStringFromObj and Tcl_Get‐
118       String to get an object's string representation.  If bytes is NULL, the
119       string representation is invalid.
120
121       An object's type manages its internal representation.  The member type‐
122       Ptr  points  to  the Tcl_ObjType structure that describes the type.  If
123       typePtr is NULL, the internal representation is invalid.
124
125       The internalRep union member holds an object's internal representation.
126       This is either a (long) integer, a double-precision floating point num‐
127       ber, a pointer to a value containing additional information  needed  by
128       the object's type to represent the object, or two arbitrary pointers.
129
130       The refCount member is used to tell when it is safe to free an object's
131       storage.  It holds the count of active references to the object.  Main‐
132       taining  the  correct reference count is a key responsibility of exten‐
133       sion writers.  Reference counting is discussed  below  in  the  section
134       STORAGE MANAGEMENT OF OBJECTS.
135
136       Although extension writers can directly access the members of a Tcl_Obj
137       structure, it is much better to  use  the  appropriate  procedures  and
138       macros.   For  example,  extension  writers should never read or update
139       refCount directly; they should use macros such as Tcl_IncrRefCount  and
140       Tcl_IsShared instead.
141
142       A  key  property  of Tcl objects is that they hold two representations.
143       An object typically starts out containing only a string representation:
144       it  is  untyped  and has a NULL typePtr.  An object containing an empty
145       string or a copy of a specified string is created using  Tcl_NewObj  or
146       Tcl_NewStringObj respectively.  An object's string value is gotten with
147       Tcl_GetStringFromObj  or  Tcl_GetString  and  changed   with   Tcl_Set‐
148       StringObj.   If the object is later passed to a procedure like Tcl_Get‐
149       IntFromObj that requires a specific internal representation, the proce‐
150       dure will create one and set the object's typePtr.  The internal repre‐
151       sentation is computed from the string representation.  An object's  two
152       representations  are  duals  of  each  other:  changes  made to one are
153       reflected in the other.  For example, Tcl_ListObjReplace will modify an
154       object's internal representation and the next call to Tcl_GetStringFro‐
155       mObj or Tcl_GetString will reflect that change.
156
157       Representations are recomputed lazily for efficiency.  A change to  one
158       representation  made  by  a procedure such as Tcl_ListObjReplace is not
159       reflected immediately in the other representation.  Instead, the  other
160       representation  is  marked invalid so that it is only regenerated if it
161       is needed later.  Most C programmers never have to  be  concerned  with
162       how  this  is done and simply use procedures such as Tcl_GetBooleanFro‐
163       mObj or Tcl_ListObjIndex.  Programmers that implement their own  object
164       types  must  check for invalid representations and mark representations
165       invalid when necessary.  The procedure Tcl_InvalidateStringRep is  used
166       to mark an object's string representation invalid and to free any stor‐
167       age associated with the old string representation.
168
169       Objects usually remain one type over their life,  but  occasionally  an
170       object  must  be  converted from one type to another.  For example, a C
171       program might build up a string in an object  with  repeated  calls  to
172       Tcl_AppendToObj,  and then call Tcl_ListObjIndex to extract a list ele‐
173       ment from the object.  The same object holding the  same  string  value
174       can have several different internal representations at different times.
175       Extension writers can also force an object to  be  converted  from  one
176       type  to  another using the Tcl_ConvertToType procedure.  Only program‐
177       mers that create new object types need to be concerned about  how  this
178       is  done.  A procedure defined as part of the object type's implementa‐
179       tion creates a new internal representation for an  object  and  changes
180       its  typePtr.   See  the man page for Tcl_RegisterObjType to see how to
181       create a new object type.
182
183

EXAMPLE OF THE LIFETIME OF AN OBJECT

185       As an example of the lifetime of  an  object,  consider  the  following
186       sequence of commands:
187              set x 123
188       This  assigns  to  x an untyped object whose bytes member points to 123
189       and length member contains 3.  The object's typePtr member is NULL.
190              puts "x is $x"
191       x's string representation is valid (since bytes  is  non-NULL)  and  is
192       fetched for the command.
193              incr x
194       The  incr  command  first  gets  an  integer from x's object by calling
195       Tcl_GetIntFromObj.  This procedure checks whether the object is already
196       an  integer object.  Since it is not, it converts the object by setting
197       the object's internalRep.longValue member to the integer 123  and  set‐
198       ting  the  object's  typePtr to point to the integer Tcl_ObjType struc‐
199       ture.   Both  representations  are  now  valid.   incr  increments  the
200       object's  integer  internal  representation then invalidates its string
201       representation (by calling Tcl_InvalidateStringRep)  since  the  string
202       representation no longer corresponds to the internal representation.
203              puts "x is now $x"
204       The  string  representation  of x's object is needed and is recomputed.
205       The string representation is now 124.   and  both  representations  are
206       again valid.
207
208

STORAGE MANAGEMENT OF OBJECTS

210       Tcl  objects are allocated on the heap and are shared as much as possi‐
211       ble to reduce storage requirements.   Reference  counting  is  used  to
212       determine  when  an object is no longer needed and can safely be freed.
213       An object just created by Tcl_NewObj or Tcl_NewStringObj  has  refCount
214       0.   The  macro  Tcl_IncrRefCount increments the reference count when a
215       new reference to the object is  created.   The  macro  Tcl_DecrRefCount
216       decrements  the  count when a reference is no longer needed and, if the
217       object's reference count drops to zero, frees its storage.   An  object
218       shared  by  different code or data structures has refCount greater than
219       1.  Incrementing an object's reference count ensures that it  won't  be
220       freed too early or have its value change accidently.
221
222       As an example, the bytecode interpreter shares argument objects between
223       calling and called Tcl procedures to avoid having to copy objects.   It
224       assigns the call's argument objects to the procedure's formal parameter
225       variables.  In doing so, it calls  Tcl_IncrRefCount  to  increment  the
226       reference  count of each argument since there is now a new reference to
227       it from the formal parameter.  When the called procedure  returns,  the
228       interpreter  calls Tcl_DecrRefCount to decrement each argument's refer‐
229       ence count.  When an object's reference count drops less than or  equal
230       to  zero,  Tcl_DecrRefCount  reclaims its storage.  Most command proce‐
231       dures do not have to be concerned about reference counting  since  they
232       use  an  object's  value  immediately and don't retain a pointer to the
233       object after they return.  However, if they do retain a pointer  to  an
234       object  in a data structure, they must be careful to increment its ref‐
235       erence count since the retained pointer is a new reference.
236
237       Command procedures that directly modify objects such as those for  lap‐
238       pend  and linsert must be careful to copy a shared object before chang‐
239       ing it.  They must first check whether the object is shared by  calling
240       Tcl_IsShared.   If  the  object  is shared they must copy the object by
241       using Tcl_DuplicateObj; this returns a new duplicate  of  the  original
242       object  that  has refCount 0.  If the object is not shared, the command
243       procedure "owns" the object and can safely  modify  it  directly.   For
244       example,  the  following  code  appears  in  the command procedure that
245       implements linsert.  This procedure modifies the list object passed  to
246       it in objv[1] by inserting objc-3 new elements before index.
247              listPtr = objv[1];
248              if (Tcl_IsShared(listPtr)) {
249                listPtr = Tcl_DuplicateObj(listPtr);
250              }
251              result = Tcl_ListObjReplace(interp, listPtr, index, 0, (objc-3), &(objv[3]));
252       As  another  example,  incr's  command procedure must check whether the
253       variable's object is shared before  incrementing  the  integer  in  its
254       internal  representation.   If  it is shared, it needs to duplicate the
255       object in order to avoid  accidently  changing  values  in  other  data
256       structures.
257
258

SEE ALSO

260       Tcl_ConvertToType,     Tcl_GetIntFromObj,     Tcl_ListObjAppendElement,
261       Tcl_ListObjIndex, Tcl_ListObjReplace, Tcl_RegisterObjType
262
263

KEYWORDS

265       internal representation, object, object creation, object  type,  refer‐
266       ence counting, string representation, type conversion
267
268
269
270Tcl                                   8.1                           Tcl_Obj(3)
Impressum