PageRenderTime 52ms CodeModel.GetById 21ms RepoModel.GetById 1ms app.codeStats 0ms

/help/02TclTk8.5/TclLib/Object.htm

https://github.com/nenopera/ramdebugger
HTML | 345 lines | 345 code | 0 blank | 0 comment | 0 complexity | 02fe707669be07953e39ad8193cf3dda MD5 | raw file
Possible License(s): AGPL-3.0
  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  2. <HTML>
  3. <HEAD><TITLE>Tcl_Obj manual page - Tcl Library Procedures</TITLE>
  4. <link rel="stylesheet" href="../docs.css" type="text/css" media="all">
  5. </HEAD>
  6. <BODY><H2><a href="../contents.htm">Tcl8.5.1/Tk8.5.1 Documentation</a> <small>&gt;</small> <a href="contents.htm">TclLib</a> <small>&gt;</small> Object</H2>
  7. <H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../TclLib/contents.htm">Tcl Library</A> | <A HREF="../TkLib/contents.htm">Tk Library</A></H3>
  8. <DL>
  9. <DD><A HREF="Object.htm#M2" NAME="L459">NAME</A>
  10. <DL><DD>Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_InvalidateStringRep - manipulate Tcl objects</DD></DL>
  11. <DD><A HREF="Object.htm#M3" NAME="L460">SYNOPSIS</A>
  12. <DL>
  13. <DD><B>#include &lt;tcl.h&gt;</B>
  14. <DD>Tcl_Obj *
  15. <DD><B>Tcl_NewObj</B>()
  16. <DD>Tcl_Obj *
  17. <DD><B>Tcl_DuplicateObj</B>(<I>objPtr</I>)
  18. <DD><B>Tcl_IncrRefCount</B>(<I>objPtr</I>)
  19. <DD><B>Tcl_DecrRefCount</B>(<I>objPtr</I>)
  20. <DD>int
  21. <DD><B>Tcl_IsShared</B>(<I>objPtr</I>)
  22. <DD><B>Tcl_InvalidateStringRep</B>(<I>objPtr</I>)
  23. </DL>
  24. <DD><A HREF="Object.htm#M4" NAME="L461">ARGUMENTS</A>
  25. <DL class="arguments">
  26. </DL>
  27. <DD><A HREF="Object.htm#M5" NAME="L462">INTRODUCTION</A>
  28. <DD><A HREF="Object.htm#M6" NAME="L463">THE TCL_OBJ STRUCTURE</A>
  29. <DD><A HREF="Object.htm#M7" NAME="L464">EXAMPLE OF THE LIFETIME OF AN OBJECT</A>
  30. <DD><A HREF="Object.htm#M8" NAME="L465">STORAGE MANAGEMENT OF OBJECTS</A>
  31. <DD><A HREF="Object.htm#M9" NAME="L466">SEE ALSO</A>
  32. <DD><A HREF="Object.htm#M10" NAME="L467">KEYWORDS</A>
  33. </DL>
  34. <H3><A NAME="M2">NAME</A></H3>
  35. Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_InvalidateStringRep - manipulate Tcl objects
  36. <H3><A NAME="M3">SYNOPSIS</A></H3>
  37. <B>#include &lt;tcl.h&gt;</B><BR>
  38. Tcl_Obj *<BR>
  39. <B>Tcl_NewObj</B>()<BR>
  40. Tcl_Obj *<BR>
  41. <B>Tcl_DuplicateObj</B>(<I>objPtr</I>)<BR>
  42. <B>Tcl_IncrRefCount</B>(<I>objPtr</I>)<BR>
  43. <B>Tcl_DecrRefCount</B>(<I>objPtr</I>)<BR>
  44. int<BR>
  45. <B>Tcl_IsShared</B>(<I>objPtr</I>)<BR>
  46. <B>Tcl_InvalidateStringRep</B>(<I>objPtr</I>)<BR>
  47. <H3><A NAME="M4">ARGUMENTS</A></H3>
  48. <DL class="arguments">
  49. <DT>Tcl_Obj <B>*objPtr</B> (in)<DD>
  50. Points to an object;
  51. must have been the result of a previous call to <B>Tcl_NewObj</B>.
  52. <P></DL>
  53. <H3><A NAME="M5">INTRODUCTION</A></H3>
  54. This man page presents an overview of Tcl objects and how they are used.
  55. It also describes generic procedures for managing Tcl objects.
  56. These procedures are used to create and copy objects,
  57. and increment and decrement the count of references (pointers) to objects.
  58. The procedures are used in conjunction with ones
  59. that operate on specific types of objects such as
  60. <B><A HREF="../TclLib/IntObj.htm">Tcl_GetIntFromObj</A></B> and <B><A HREF="../TclLib/ListObj.htm">Tcl_ListObjAppendElement</A></B>.
  61. The individual procedures are described along with the data structures
  62. they manipulate.
  63. <P>
  64. Tcl's <I>dual-ported</I> objects provide a general-purpose mechanism
  65. for storing and exchanging Tcl values.
  66. They largely replace the use of strings in Tcl.
  67. For example, they are used to store variable values,
  68. command arguments, command results, and scripts.
  69. Tcl objects behave like strings but also hold an internal representation
  70. that can be manipulated more efficiently.
  71. For example, a Tcl list is now represented as an object
  72. that holds the list's string representation
  73. as well as an array of pointers to the objects for each list element.
  74. Dual-ported objects avoid most runtime type conversions.
  75. They also improve the speed of many operations
  76. since an appropriate representation is immediately available.
  77. The compiler itself uses Tcl objects to
  78. cache the instruction bytecodes resulting from compiling scripts.
  79. <P>
  80. The two representations are a cache of each other and are computed lazily.
  81. That is, each representation is only computed when necessary,
  82. it is computed from the other representation,
  83. and, once computed, it is saved.
  84. In addition, a change in one representation invalidates the other one.
  85. As an example, a Tcl program doing integer calculations can
  86. operate directly on a variable's internal machine integer
  87. representation without having to constantly convert
  88. between integers and strings.
  89. Only when it needs a string representing the variable's value,
  90. say to print it,
  91. will the program regenerate the string representation from the integer.
  92. Although objects contain an internal representation,
  93. their semantics are defined in terms of strings:
  94. an up-to-date string can always be obtained,
  95. and any change to the object will be reflected in that string
  96. when the object's string representation is fetched.
  97. Because of this representation invalidation and regeneration,
  98. it is dangerous for extension writers to access
  99. <B>Tcl_Obj</B> fields directly.
  100. It is better to access Tcl_Obj information using
  101. procedures like <B><A HREF="../TclLib/StringObj.htm">Tcl_GetStringFromObj</A></B> and <B><A HREF="../TclLib/StringObj.htm">Tcl_GetString</A></B>.
  102. <P>
  103. Objects are allocated on the heap
  104. and are referenced using a pointer to their <B>Tcl_Obj</B> structure.
  105. Objects are shared as much as possible.
  106. This significantly reduces storage requirements
  107. because some objects such as long lists are very large.
  108. Also, most Tcl values are only read and never modified.
  109. This is especially true for procedure arguments,
  110. which can be shared between the caller and the called procedure.
  111. Assignment and argument binding is done by
  112. simply assigning a pointer to the value.
  113. Reference counting is used to determine when it is safe to
  114. reclaim an object's storage.
  115. <P>
  116. Tcl objects are typed.
  117. An object's internal representation is controlled by its type.
  118. Seven types are predefined in the Tcl core
  119. including integer, double, list, and bytecode.
  120. Extension writers can extend the set of types
  121. by using the procedure <B><A HREF="../TclLib/ObjectType.htm">Tcl_RegisterObjType</A></B> .
  122. <H3><A NAME="M6">THE TCL_OBJ STRUCTURE</A></H3>
  123. Each Tcl object is represented by a <B>Tcl_Obj</B> structure
  124. which is defined as follows.
  125. <PRE>typedef struct Tcl_Obj {
  126. int <I>refCount</I>;
  127. char *<I>bytes</I>;
  128. int <I>length</I>;
  129. Tcl_ObjType *<I>typePtr</I>;
  130. union {
  131. long <I>longValue</I>;
  132. double <I>doubleValue</I>;
  133. void *<I>otherValuePtr</I>;
  134. Tcl_WideInt <I>wideValue</I>;
  135. struct {
  136. void *<I>ptr1</I>;
  137. void *<I>ptr2</I>;
  138. } <I>twoPtrValue</I>;
  139. struct {
  140. void *<I>ptr</I>;
  141. unsigned long <I>value</I>;
  142. } <I>ptrAndLongRep</I>;
  143. } <I>internalRep</I>;
  144. } Tcl_Obj;</PRE>
  145. The <I>bytes</I> and the <I>length</I> members together hold
  146. an object's UTF-8 string representation,
  147. which is a <I>counted string</I> not containing null bytes (UTF-8 null
  148. characters should be encoded as a two byte sequence: 192, 128.)
  149. <I>bytes</I> points to the first byte of the string representation.
  150. The <I>length</I> member gives the number of bytes.
  151. The byte array must always have a null byte after the last data byte,
  152. at offset <I>length</I>;
  153. this allows string representations
  154. to be treated as conventional null-terminated C strings.
  155. C programs use <B><A HREF="../TclLib/StringObj.htm">Tcl_GetStringFromObj</A></B> and <B><A HREF="../TclLib/StringObj.htm">Tcl_GetString</A></B> to get
  156. an object's string representation.
  157. If <I>bytes</I> is NULL,
  158. the string representation is invalid.
  159. <P>
  160. An object's type manages its internal representation.
  161. The member <I>typePtr</I> points to the Tcl_ObjType structure
  162. that describes the type.
  163. If <I>typePtr</I> is NULL,
  164. the internal representation is invalid.
  165. <P>
  166. The <I>internalRep</I> union member holds
  167. an object's internal representation.
  168. This is either a (long) integer, a double-precision floating-point number,
  169. a pointer to a value containing additional information
  170. needed by the object's type to represent the object, a Tcl_WideInt
  171. integer, two arbitrary pointers, or a pair made up of an unsigned long
  172. integer and a pointer.
  173. <P>
  174. The <I>refCount</I> member is used to tell when it is safe to free
  175. an object's storage.
  176. It holds the count of active references to the object.
  177. Maintaining the correct reference count is a key responsibility
  178. of extension writers.
  179. Reference counting is discussed below
  180. in the section <B>STORAGE MANAGEMENT OF OBJECTS</B>.
  181. <P>
  182. Although extension writers can directly access
  183. the members of a Tcl_Obj structure,
  184. it is much better to use the appropriate procedures and macros.
  185. For example, extension writers should never
  186. read or update <I>refCount</I> directly;
  187. they should use macros such as
  188. <B>Tcl_IncrRefCount</B> and <B>Tcl_IsShared</B> instead.
  189. <P>
  190. A key property of Tcl objects is that they hold two representations.
  191. An object typically starts out containing only a string representation:
  192. it is untyped and has a NULL <I>typePtr</I>.
  193. An object containing an empty string or a copy of a specified string
  194. is created using <B>Tcl_NewObj</B> or <B><A HREF="../TclLib/StringObj.htm">Tcl_NewStringObj</A></B> respectively.
  195. An object's string value is gotten with
  196. <B><A HREF="../TclLib/StringObj.htm">Tcl_GetStringFromObj</A></B> or <B><A HREF="../TclLib/StringObj.htm">Tcl_GetString</A></B>
  197. and changed with <B><A HREF="../TclLib/StringObj.htm">Tcl_SetStringObj</A></B>.
  198. If the object is later passed to a procedure like <B><A HREF="../TclLib/IntObj.htm">Tcl_GetIntFromObj</A></B>
  199. that requires a specific internal representation,
  200. the procedure will create one and set the object's <I>typePtr</I>.
  201. The internal representation is computed from the string representation.
  202. An object's two representations are duals of each other:
  203. changes made to one are reflected in the other.
  204. For example, <B><A HREF="../TclLib/ListObj.htm">Tcl_ListObjReplace</A></B> will modify an object's
  205. internal representation and the next call to <B><A HREF="../TclLib/StringObj.htm">Tcl_GetStringFromObj</A></B>
  206. or <B><A HREF="../TclLib/StringObj.htm">Tcl_GetString</A></B> will reflect that change.
  207. <P>
  208. Representations are recomputed lazily for efficiency.
  209. A change to one representation made by a procedure
  210. such as <B><A HREF="../TclLib/ListObj.htm">Tcl_ListObjReplace</A></B> is not reflected immediately
  211. in the other representation.
  212. Instead, the other representation is marked invalid
  213. so that it is only regenerated if it is needed later.
  214. Most C programmers never have to be concerned with how this is done
  215. and simply use procedures such as <B><A HREF="../TclLib/BoolObj.htm">Tcl_GetBooleanFromObj</A></B> or
  216. <B><A HREF="../TclLib/ListObj.htm">Tcl_ListObjIndex</A></B>.
  217. Programmers that implement their own object types
  218. must check for invalid representations
  219. and mark representations invalid when necessary.
  220. The procedure <B>Tcl_InvalidateStringRep</B> is used
  221. to mark an object's string representation invalid and to
  222. free any storage associated with the old string representation.
  223. <P>
  224. Objects usually remain one type over their life,
  225. but occasionally an object must be converted from one type to another.
  226. For example, a C program might build up a string in an object
  227. with repeated calls to <B><A HREF="../TclLib/StringObj.htm">Tcl_AppendToObj</A></B>,
  228. and then call <B><A HREF="../TclLib/ListObj.htm">Tcl_ListObjIndex</A></B> to extract a list element from
  229. the object.
  230. The same object holding the same string value
  231. can have several different internal representations
  232. at different times.
  233. Extension writers can also force an object to be converted from one type
  234. to another using the <B><A HREF="../TclLib/ObjectType.htm">Tcl_ConvertToType</A></B> procedure.
  235. Only programmers that create new object types need to be concerned
  236. about how this is done.
  237. A procedure defined as part of the object type's implementation
  238. creates a new internal representation for an object
  239. and changes its <I>typePtr</I>.
  240. See the man page for <B><A HREF="../TclLib/ObjectType.htm">Tcl_RegisterObjType</A></B>
  241. to see how to create a new object type.
  242. <H3><A NAME="M7">EXAMPLE OF THE LIFETIME OF AN OBJECT</A></H3>
  243. As an example of the lifetime of an object,
  244. consider the following sequence of commands:
  245. <PRE><B>set x 123</B></PRE>
  246. This assigns to <I>x</I> an untyped object whose
  247. <I>bytes</I> member points to <B>123</B> and <I>length</I> member contains 3.
  248. The object's <I>typePtr</I> member is NULL.
  249. <PRE><B>puts &quot;x is $x&quot;</B></PRE>
  250. <I>x</I>'s string representation is valid (since <I>bytes</I> is non-NULL)
  251. and is fetched for the command.
  252. <PRE><B>incr x</B></PRE>
  253. The <B><A HREF="../TclCmd/incr.htm">incr</A></B> command first gets an integer from <I>x</I>'s object
  254. by calling <B><A HREF="../TclLib/IntObj.htm">Tcl_GetIntFromObj</A></B>.
  255. This procedure checks whether the object is already an integer object.
  256. Since it is not, it converts the object
  257. by setting the object's <I>internalRep.longValue</I> member
  258. to the integer <B>123</B>
  259. and setting the object's <I>typePtr</I>
  260. to point to the integer Tcl_ObjType structure.
  261. Both representations are now valid.
  262. <B><A HREF="../TclCmd/incr.htm">incr</A></B> increments the object's integer internal representation
  263. then invalidates its string representation
  264. (by calling <B>Tcl_InvalidateStringRep</B>)
  265. since the string representation
  266. no longer corresponds to the internal representation.
  267. <PRE><B>puts &quot;x is now $x&quot;</B></PRE>
  268. The string representation of <I>x</I>'s object is needed
  269. and is recomputed.
  270. The string representation is now <B>124</B>
  271. and both representations are again valid.
  272. <H3><A NAME="M8">STORAGE MANAGEMENT OF OBJECTS</A></H3>
  273. Tcl objects are allocated on the heap and are shared as much as possible
  274. to reduce storage requirements.
  275. Reference counting is used to determine when an object is
  276. no longer needed and can safely be freed.
  277. An object just created by <B>Tcl_NewObj</B> or <B><A HREF="../TclLib/StringObj.htm">Tcl_NewStringObj</A></B>
  278. has <I>refCount</I> 0.
  279. The macro <B>Tcl_IncrRefCount</B> increments the reference count
  280. when a new reference to the object is created.
  281. The macro <B>Tcl_DecrRefCount</B> decrements the count
  282. when a reference is no longer needed and,
  283. if the object's reference count drops to zero, frees its storage.
  284. An object shared by different code or data structures has
  285. <I>refCount</I> greater than 1.
  286. Incrementing an object's reference count ensures that
  287. it will not be freed too early or have its value change accidentally.
  288. <P>
  289. As an example, the bytecode interpreter shares argument objects
  290. between calling and called Tcl procedures to avoid having to copy objects.
  291. It assigns the call's argument objects to the procedure's
  292. formal parameter variables.
  293. In doing so, it calls <B>Tcl_IncrRefCount</B> to increment
  294. the reference count of each argument since there is now a new
  295. reference to it from the formal parameter.
  296. When the called procedure returns,
  297. the interpreter calls <B>Tcl_DecrRefCount</B> to decrement
  298. each argument's reference count.
  299. When an object's reference count drops less than or equal to zero,
  300. <B>Tcl_DecrRefCount</B> reclaims its storage.
  301. Most command procedures do not have to be concerned about
  302. reference counting since they use an object's value immediately
  303. and do not retain a pointer to the object after they return.
  304. However, if they do retain a pointer to an object in a data structure,
  305. they must be careful to increment its reference count
  306. since the retained pointer is a new reference.
  307. <P>
  308. Command procedures that directly modify objects
  309. such as those for <B><A HREF="../TclCmd/lappend.htm">lappend</A></B> and <B><A HREF="../TclCmd/linsert.htm">linsert</A></B> must be careful to
  310. copy a shared object before changing it.
  311. They must first check whether the object is shared
  312. by calling <B>Tcl_IsShared</B>.
  313. If the object is shared they must copy the object
  314. by using <B>Tcl_DuplicateObj</B>;
  315. this returns a new duplicate of the original object
  316. that has <I>refCount</I> 0.
  317. If the object is not shared,
  318. the command procedure
  319. &#8220;owns&#8221;
  320. the object and can safely modify it directly.
  321. For example, the following code appears in the command procedure
  322. that implements <B><A HREF="../TclCmd/linsert.htm">linsert</A></B>.
  323. This procedure modifies the list object passed to it in <I>objv[1]</I>
  324. by inserting <I>objc-3</I> new elements before <I>index</I>.
  325. <P>
  326. <PRE>listPtr = objv[1];
  327. if (Tcl_IsShared(listPtr)) {
  328. listPtr = Tcl_DuplicateObj(listPtr);
  329. }
  330. result = <A HREF="../TclLib/ListObj.htm">Tcl_ListObjReplace</A>(interp, listPtr, index, 0,
  331. (objc-3), &amp;(objv[3]));</PRE>
  332. <P>
  333. As another example, <B><A HREF="../TclCmd/incr.htm">incr</A></B>'s command procedure
  334. must check whether the variable's object is shared before
  335. incrementing the integer in its internal representation.
  336. If it is shared, it needs to duplicate the object
  337. in order to avoid accidentally changing values in other data structures.
  338. <H3><A NAME="M9">SEE ALSO</A></H3>
  339. <B><A HREF="../TclLib/ObjectType.htm">Tcl_ConvertToType</A></B>, <B><A HREF="../TclLib/IntObj.htm">Tcl_GetIntFromObj</A></B>, <B><A HREF="../TclLib/ListObj.htm">Tcl_ListObjAppendElement</A></B>, <B><A HREF="../TclLib/ListObj.htm">Tcl_ListObjIndex</A></B>, <B><A HREF="../TclLib/ListObj.htm">Tcl_ListObjReplace</A></B>, <B><A HREF="../TclLib/ObjectType.htm">Tcl_RegisterObjType</A></B>
  340. <H3><A NAME="M10">KEYWORDS</A></H3>
  341. <A href="../Keywords/I.htm#internal representation">internal representation</A>, <A href="../Keywords/O.htm#object">object</A>, <A href="../Keywords/O.htm#object creation">object creation</A>, <A href="../Keywords/O.htm#object type">object type</A>, <A href="../Keywords/R.htm#reference counting">reference counting</A>, <A href="../Keywords/S.htm#string representation">string representation</A>, <A href="../Keywords/T.htm#type conversion">type conversion</A>
  342. <div class="copy">Copyright &copy; 1995-1997 Roger E. Critchlow Jr.
  343. Copyright &copy; 1996-1997 Sun Microsystems, Inc.
  344. </div>
  345. </BODY></HTML>