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 values
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 a value;  must  have  been  the
31                                     result of a previous call to Tcl_NewObj.
32______________________________________________________________________________
33

INTRODUCTION

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
44       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
57       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
75       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
85       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

THE TCL_OBJ STRUCTURE

91       Each Tcl value is represented by a Tcl_Obj structure which  is  defined
92       as follows.
93
94              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
115       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
126       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
130       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
137       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
143       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
149       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
164       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
176       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

EXAMPLE OF THE LIFETIME OF A VALUE

191       As an example of the  lifetime  of  a  value,  consider  the  following
192       sequence of commands:
193
194              set x 123
195
196       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
199              puts "x is $x"
200
201       x's string representation is valid (since bytes  is  non-NULL)  and  is
202       fetched for the command.
203
204              incr x
205
206       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
216              puts "x is now $x"
217
218       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

STORAGE MANAGEMENT OF VALUES

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
235       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
250       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
261              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
268       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

SEE ALSO

275       Tcl_ConvertToType(3),    Tcl_GetIntFromObj(3),    Tcl_ListObjAppendEle‐
276       ment(3), Tcl_ListObjIndex(3),  Tcl_ListObjReplace(3),  Tcl_RegisterObj‐
277       Type(3)
278

KEYWORDS

280       internal  representation,  value, value creation, value type, reference
281       counting, string representation, type conversion
282
283
284
285Tcl                                   8.5                           Tcl_Obj(3)
Impressum