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.  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

THE TCL_OBJ STRUCTURE

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
125       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
129       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
136       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
142       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
148       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
163       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
175       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

EXAMPLE OF THE LIFETIME OF AN OBJECT

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

STORAGE MANAGEMENT OF OBJECTS

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
226       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
241       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
252              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
259       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

SEE ALSO

266       Tcl_ConvertToType(3),    Tcl_GetIntFromObj(3),    Tcl_ListObjAppendEle‐
267       ment(3), Tcl_ListObjIndex(3),  Tcl_ListObjReplace(3),  Tcl_RegisterObj‐
268       Type(3)
269

KEYWORDS

271       internal  representation,  object, object creation, object type, refer‐
272       ence counting, string representation, type conversion
273
274
275
276Tcl                                   8.5                           Tcl_Obj(3)
Impressum