diff options
Diffstat (limited to 'tcl8.6/doc/Object.3')
| -rw-r--r-- | tcl8.6/doc/Object.3 | 352 |
1 files changed, 352 insertions, 0 deletions
diff --git a/tcl8.6/doc/Object.3 b/tcl8.6/doc/Object.3 new file mode 100644 index 0000000..bf80fe2 --- /dev/null +++ b/tcl8.6/doc/Object.3 @@ -0,0 +1,352 @@ +'\" +'\" Copyright (c) 1996-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tcl_Obj 3 8.5 Tcl "Tcl Library Procedures" +.so man.macros +.BS +.SH NAME +Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_InvalidateStringRep \- manipulate Tcl values +.SH SYNOPSIS +.nf +\fB#include <tcl.h>\fR +.sp +Tcl_Obj * +\fBTcl_NewObj\fR() +.sp +Tcl_Obj * +\fBTcl_DuplicateObj\fR(\fIobjPtr\fR) +.sp +\fBTcl_IncrRefCount\fR(\fIobjPtr\fR) +.sp +\fBTcl_DecrRefCount\fR(\fIobjPtr\fR) +.sp +int +\fBTcl_IsShared\fR(\fIobjPtr\fR) +.sp +\fBTcl_InvalidateStringRep\fR(\fIobjPtr\fR) +.SH ARGUMENTS +.AS Tcl_Obj *objPtr +.AP Tcl_Obj *objPtr in +Points to a value; +must have been the result of a previous call to \fBTcl_NewObj\fR. +.BE +.SH INTRODUCTION +.PP +This man page presents an overview of Tcl values (called \fBTcl_Obj\fRs for +historical reasons) and how they are used. +It also describes generic procedures for managing Tcl values. +These procedures are used to create and copy values, +and increment and decrement the count of references (pointers) to values. +The procedures are used in conjunction with ones +that operate on specific types of values such as +\fBTcl_GetIntFromObj\fR and \fBTcl_ListObjAppendElement\fR. +The individual procedures are described along with the data structures +they manipulate. +.PP +Tcl's \fIdual-ported\fR values provide a general-purpose mechanism +for storing and exchanging Tcl values. +They largely replace the use of strings in Tcl. +For example, they are used to store variable values, +command arguments, command results, and scripts. +Tcl values behave like strings but also hold an internal representation +that can be manipulated more efficiently. +For example, a Tcl list is now represented as a value +that holds the list's string representation +as well as an array of pointers to the values for each list element. +Dual-ported values avoid most runtime type conversions. +They also improve the speed of many operations +since an appropriate representation is immediately available. +The compiler itself uses Tcl values to +cache the instruction bytecodes resulting from compiling scripts. +.PP +The two representations are a cache of each other and are computed lazily. +That is, each representation is only computed when necessary, +it is computed from the other representation, +and, once computed, it is saved. +In addition, a change in one representation invalidates the other one. +As an example, a Tcl program doing integer calculations can +operate directly on a variable's internal machine integer +representation without having to constantly convert +between integers and strings. +Only when it needs a string representing the variable's value, +say to print it, +will the program regenerate the string representation from the integer. +Although values contain an internal representation, +their semantics are defined in terms of strings: +an up-to-date string can always be obtained, +and any change to the value will be reflected in that string +when the value's string representation is fetched. +Because of this representation invalidation and regeneration, +it is dangerous for extension writers to access +\fBTcl_Obj\fR fields directly. +It is better to access Tcl_Obj information using +procedures like \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR. +.PP +Values are allocated on the heap +and are referenced using a pointer to their \fBTcl_Obj\fR structure. +Values are shared as much as possible. +This significantly reduces storage requirements +because some values such as long lists are very large. +Also, most Tcl values are only read and never modified. +This is especially true for procedure arguments, +which can be shared between the caller and the called procedure. +Assignment and argument binding is done by +simply assigning a pointer to the value. +Reference counting is used to determine when it is safe to +reclaim a value's storage. +.PP +Tcl values are typed. +A value's internal representation is controlled by its type. +Several types are predefined in the Tcl core +including integer, double, list, and bytecode. +Extension writers can extend the set of types +by defining their own \fBTcl_ObjType\fR structs. +.SH "THE TCL_OBJ STRUCTURE" +.PP +Each Tcl value is represented by a \fBTcl_Obj\fR structure +which is defined as follows. +.PP +.CS +typedef struct Tcl_Obj { + int \fIrefCount\fR; + char *\fIbytes\fR; + int \fIlength\fR; + const Tcl_ObjType *\fItypePtr\fR; + union { + long \fIlongValue\fR; + double \fIdoubleValue\fR; + void *\fIotherValuePtr\fR; + Tcl_WideInt \fIwideValue\fR; + struct { + void *\fIptr1\fR; + void *\fIptr2\fR; + } \fItwoPtrValue\fR; + struct { + void *\fIptr\fR; + unsigned long \fIvalue\fR; + } \fIptrAndLongRep\fR; + } \fIinternalRep\fR; +} \fBTcl_Obj\fR; +.CE +.PP +The \fIbytes\fR and the \fIlength\fR members together hold +a value's UTF-8 string representation, +which is a \fIcounted string\fR not containing null bytes (UTF-8 null +characters should be encoded as a two byte sequence: 192, 128.) +\fIbytes\fR points to the first byte of the string representation. +The \fIlength\fR member gives the number of bytes. +The byte array must always have a null byte after the last data byte, +at offset \fIlength\fR; +this allows string representations +to be treated as conventional null-terminated C strings. +C programs use \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR to get +a value's string representation. +If \fIbytes\fR is NULL, +the string representation is invalid. +.PP +A value's type manages its internal representation. +The member \fItypePtr\fR points to the Tcl_ObjType structure +that describes the type. +If \fItypePtr\fR is NULL, +the internal representation is invalid. +.PP +The \fIinternalRep\fR union member holds +a value's internal representation. +This is either a (long) integer, a double-precision floating-point number, +a pointer to a value containing additional information +needed by the value's type to represent the value, a Tcl_WideInt +integer, two arbitrary pointers, or a pair made up of an unsigned long +integer and a pointer. +.PP +The \fIrefCount\fR member is used to tell when it is safe to free +a value's storage. +It holds the count of active references to the value. +Maintaining the correct reference count is a key responsibility +of extension writers. +Reference counting is discussed below +in the section \fBSTORAGE MANAGEMENT OF VALUES\fR. +.PP +Although extension writers can directly access +the members of a Tcl_Obj structure, +it is much better to use the appropriate procedures and macros. +For example, extension writers should never +read or update \fIrefCount\fR directly; +they should use macros such as +\fBTcl_IncrRefCount\fR and \fBTcl_IsShared\fR instead. +.PP +A key property of Tcl values is that they hold two representations. +A value typically starts out containing only a string representation: +it is untyped and has a NULL \fItypePtr\fR. +A value containing an empty string or a copy of a specified string +is created using \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR respectively. +A value's string value is gotten with +\fBTcl_GetStringFromObj\fR or \fBTcl_GetString\fR +and changed with \fBTcl_SetStringObj\fR. +If the value is later passed to a procedure like \fBTcl_GetIntFromObj\fR +that requires a specific internal representation, +the procedure will create one and set the value's \fItypePtr\fR. +The internal representation is computed from the string representation. +A value's two representations are duals of each other: +changes made to one are reflected in the other. +For example, \fBTcl_ListObjReplace\fR will modify a value's +internal representation and the next call to \fBTcl_GetStringFromObj\fR +or \fBTcl_GetString\fR will reflect that change. +.PP +Representations are recomputed lazily for efficiency. +A change to one representation made by a procedure +such as \fBTcl_ListObjReplace\fR is not reflected immediately +in the other representation. +Instead, the other representation is marked invalid +so that it is only regenerated if it is needed later. +Most C programmers never have to be concerned with how this is done +and simply use procedures such as \fBTcl_GetBooleanFromObj\fR or +\fBTcl_ListObjIndex\fR. +Programmers that implement their own value types +must check for invalid representations +and mark representations invalid when necessary. +The procedure \fBTcl_InvalidateStringRep\fR is used +to mark a value's string representation invalid and to +free any storage associated with the old string representation. +.PP +Values usually remain one type over their life, +but occasionally a value must be converted from one type to another. +For example, a C program might build up a string in a value +with repeated calls to \fBTcl_AppendToObj\fR, +and then call \fBTcl_ListObjIndex\fR to extract a list element from +the value. +The same value holding the same string value +can have several different internal representations +at different times. +Extension writers can also force a value to be converted from one type +to another using the \fBTcl_ConvertToType\fR procedure. +Only programmers that create new value types need to be concerned +about how this is done. +A procedure defined as part of the value type's implementation +creates a new internal representation for a value +and changes its \fItypePtr\fR. +See the man page for \fBTcl_RegisterObjType\fR +to see how to create a new value type. +.SH "EXAMPLE OF THE LIFETIME OF A VALUE" +.PP +As an example of the lifetime of a value, +consider the following sequence of commands: +.PP +.CS +\fBset x 123\fR +.CE +.PP +This assigns to \fIx\fR an untyped value whose +\fIbytes\fR member points to \fB123\fR and \fIlength\fR member contains 3. +The value's \fItypePtr\fR member is NULL. +.PP +.CS +\fBputs "x is $x"\fR +.CE +.PP +\fIx\fR's string representation is valid (since \fIbytes\fR is non-NULL) +and is fetched for the command. +.PP +.CS +\fBincr x\fR +.CE +.PP +The \fBincr\fR command first gets an integer from \fIx\fR's value +by calling \fBTcl_GetIntFromObj\fR. +This procedure checks whether the value is already an integer value. +Since it is not, it converts the value +by setting the value's \fIinternalRep.longValue\fR member +to the integer \fB123\fR +and setting the value's \fItypePtr\fR +to point to the integer Tcl_ObjType structure. +Both representations are now valid. +\fBincr\fR increments the value's integer internal representation +then invalidates its string representation +(by calling \fBTcl_InvalidateStringRep\fR) +since the string representation +no longer corresponds to the internal representation. +.PP +.CS +\fBputs "x is now $x"\fR +.CE +.PP +The string representation of \fIx\fR's value is needed +and is recomputed. +The string representation is now \fB124\fR +and both representations are again valid. +.SH "STORAGE MANAGEMENT OF VALUES" +.PP +Tcl values are allocated on the heap and are shared as much as possible +to reduce storage requirements. +Reference counting is used to determine when a value is +no longer needed and can safely be freed. +A value just created by \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR +has \fIrefCount\fR 0. +The macro \fBTcl_IncrRefCount\fR increments the reference count +when a new reference to the value is created. +The macro \fBTcl_DecrRefCount\fR decrements the count +when a reference is no longer needed and, +if the value's reference count drops to zero, frees its storage. +A value shared by different code or data structures has +\fIrefCount\fR greater than 1. +Incrementing a value's reference count ensures that +it will not be freed too early or have its value change accidentally. +.PP +As an example, the bytecode interpreter shares argument values +between calling and called Tcl procedures to avoid having to copy values. +It assigns the call's argument values to the procedure's +formal parameter variables. +In doing so, it calls \fBTcl_IncrRefCount\fR to increment +the reference count of each argument since there is now a new +reference to it from the formal parameter. +When the called procedure returns, +the interpreter calls \fBTcl_DecrRefCount\fR to decrement +each argument's reference count. +When a value's reference count drops less than or equal to zero, +\fBTcl_DecrRefCount\fR reclaims its storage. +Most command procedures do not have to be concerned about +reference counting since they use a value's value immediately +and do not retain a pointer to the value after they return. +However, if they do retain a pointer to a value in a data structure, +they must be careful to increment its reference count +since the retained pointer is a new reference. +.PP +Command procedures that directly modify values +such as those for \fBlappend\fR and \fBlinsert\fR must be careful to +copy a shared value before changing it. +They must first check whether the value is shared +by calling \fBTcl_IsShared\fR. +If the value is shared they must copy the value +by using \fBTcl_DuplicateObj\fR; +this returns a new duplicate of the original value +that has \fIrefCount\fR 0. +If the value is not shared, +the command procedure +.QW "owns" +the value and can safely modify it directly. +For example, the following code appears in the command procedure +that implements \fBlinsert\fR. +This procedure modifies the list value passed to it in \fIobjv[1]\fR +by inserting \fIobjc-3\fR new elements before \fIindex\fR. +.PP +.CS +listPtr = objv[1]; +if (\fBTcl_IsShared\fR(listPtr)) { + listPtr = \fBTcl_DuplicateObj\fR(listPtr); +} +result = Tcl_ListObjReplace(interp, listPtr, index, 0, + (objc-3), &(objv[3])); +.CE +.PP +As another example, \fBincr\fR's command procedure +must check whether the variable's value is shared before +incrementing the integer in its internal representation. +If it is shared, it needs to duplicate the value +in order to avoid accidentally changing values in other data structures. +.SH "SEE ALSO" +Tcl_ConvertToType(3), Tcl_GetIntFromObj(3), Tcl_ListObjAppendElement(3), Tcl_ListObjIndex(3), Tcl_ListObjReplace(3), Tcl_RegisterObjType(3) +.SH KEYWORDS +internal representation, value, value creation, value type, +reference counting, string representation, type conversion |