Let's review the SetResult.3 changes in trunk (which were never backported to 8.6/8.7)

1 files changed, 172 insertions, 67 deletions

diff --git a/doc/SetResult.3 b/doc/SetResult.3
index 954906a..9e009fa 100644
--- a/doc/SetResult.3
+++ b/doc/SetResult.3
@@ -35,105 +35,210 @@ const char *
 .SH ARGUMENTS
 .AS Tcl_FreeProc sourceInterp out
 .AP Tcl_Interp *interp out
-The interpreter get or set the result for.
+Interpreter whose result is to be modified or read.
 .AP Tcl_Obj *objPtr in
-A value to set the result to.
+Tcl value to become result for \fIinterp\fR.
 .AP char *result in
-The string value set the result to, or to append to the existing result.
+String value to become result for \fIinterp\fR or to be
+appended to the existing result.
 .AP "const char" *element in
-The string value to append as a list element
+String value to append as a list element
 to the existing result of \fIinterp\fR.
 .AP Tcl_FreeProc *freeProc in
-Pointer to a procedure to call to release storage at
-\fIresult\fR.
+Address of procedure to call to release storage at
+\fIresult\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or
+\fBTCL_VOLATILE\fR.
 .AP Tcl_Interp *sourceInterp in
-The interpreter to transfer the result and return options from.
+Interpreter that the result and return options should be transferred from.
 .AP Tcl_Interp *targetInterp in
-The interpreter to transfer the result and return options to.
+Interpreter that the result and return options should be transferred to.
 .AP int code in
 Return code value that controls transfer of return options.
 .BE
 .SH DESCRIPTION
 .PP
-These procedures manipulate the result of an interpreter.  Some procedures
-provide a Tcl_Obj interface while others provide a string interface.  For
-example, \fBTcl_SetObjResult\fR accepts a Tcl_Obj and \fBTcl_SetResult\fR
-accepts a char *.  Similarly, \fBTcl_GetObjResult\fR produces a Tcl_Obj * and
-\fBTcl_GetStringResult\fR produces a char *.  The procedures can be mixed and
-matched.  For example, if \fBTcl_SetObjResult\fR is called to set the result to
-a Tcl_Obj value, and then \fBTcl_GetStringResult\fR is called, it returns a
-char * (but see caveats below).
+The procedures described here are utilities for manipulating the
+result value in a Tcl interpreter.
+The interpreter result may be either a Tcl value or a string.
+For example, \fBTcl_SetObjResult\fR and \fBTcl_SetResult\fR
+set the interpreter result to, respectively, a value and a string.
+Similarly, \fBTcl_GetObjResult\fR and \fBTcl_GetStringResult\fR
+return the interpreter result as a value and as a string.
+The procedures always keep the string and value forms
+of the interpreter result consistent.
+For example, if \fBTcl_SetObjResult\fR is called to set
+the result to a value,
+then \fBTcl_GetStringResult\fR is called,
+it will return the value's string representation.
 .PP
-\fBTcl_SetObjResult\fR sets \fIobjPtr\fR as the result for \fIinterp\fR,
+\fBTcl_SetObjResult\fR
+arranges for \fIobjPtr\fR to be the result for \fIinterp\fR,
 replacing any existing result.
+The result is left pointing to the value
+referenced by \fIobjPtr\fR.
+\fIobjPtr\fR's reference count is incremented
+since there is now a new reference to it from \fIinterp\fR.
+The reference count for any old result value
+is decremented and the old result value is freed if no
+references to it remain.
 .PP
-\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR, without
-incrementing its reference count.
-.PP
-\fBTcl_SetResult\fR sets \fIresult\fR as the result for \fIinterp\fR, replacing
-any existing result, and calls \fIfreeProc\fR to free \fIresult\fR.  See \fBTHE
-TCL_FREEPROC ARGUMENT TO TCL_SETRESULT\fR below.  If \fIresult\fR is
-\fBNULL\fR, ignores \fIfreeProc\fR and sets the result for \fIinterp\fR to
-point to the empty string.
-.PP
-\fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as a string, i.e.
-the bytes of the Tcl_Obj for the result, which can be decoded using
-\fBTcl_UtfToExternal\fR.  This value is freed when its corresponding Tcl_Obj is
-freed.Programmers are encouraged to use the newer Tcl_Obj API procedures, e.g.
-to call \fBTcl_GetObjResult\fR instead.
-.PP
-\fBTcl_ResetResult\fR sets the empty string as the result for \fIinterp\fR and
-clears the error state managed by \fBTcl_AddErrorInfo\fR,
-\fBTcl_AddObjErrorInfo\fR, and \fBTcl_SetErrorCode\fR.
-.PP
-\fBTcl_AppendResult\fR builds up a result from smaller pieces, appending each
-\fIresult\fR in order to the current result for \fIinterp\fR.  It may be called
-repeatedly as additional pieces of the result are produced, and manages the
-storage for the \fIinterp\fR's result, allocating a larger result area if
-necessary.  It also manages conversion to and from the \fIresult\fR field of
-the \fIinterp\fR to handle backward-compatibility with old-style extensions.
-Any number of \fIresult\fR arguments may be passed in a single call; the last
-argument in the list must be (char *)NULL.
-.PP
-\fBTcl_TransferResult\fR transfers interpreter state from \fIsourceInterp\fR to
-\fItargetInterp\fR, both of which must have been created in the same thread,
-resets the result in \fIsourceInterp\fR, and moves the return options
-dictionary as controlled by the return code value \fIcode\fR in the same manner
-as \fBTcl_GetReturnOptions\fR.
+\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as a value.
+The value's reference count is not incremented;
+if the caller needs to retain a long-term pointer to the value
+they should use \fBTcl_IncrRefCount\fR to increment its reference count
+in order to keep it from being freed too early or accidentally changed.
+.PP
+\fBTcl_SetResult\fR
+arranges for \fIresult\fR to be the result for the current Tcl
+command in \fIinterp\fR, replacing any existing result.
+The \fIfreeProc\fR argument specifies how to manage the storage
+for the \fIresult\fR argument;
+it is discussed in the section
+\fBTHE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT\fR below.
+If \fIresult\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored
+and \fBTcl_SetResult\fR
+re-initializes \fIinterp\fR's result to point to an empty string.
+.PP
+\fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as a string.
+If the result was set to a value by a \fBTcl_SetObjResult\fR call,
+the value form will be converted to a string and returned.
+If the value's string representation contains null bytes,
+this conversion will lose information.
+For this reason, programmers are encouraged to
+write their code to use the new value API procedures
+and to call \fBTcl_GetObjResult\fR instead.
+.PP
+\fBTcl_ResetResult\fR clears the result for \fIinterp\fR
+and leaves the result in its normal empty initialized state.
+If the result is a value,
+its reference count is decremented and the result is left
+pointing to an unshared value representing an empty string.
+If the result is a dynamically allocated string, its memory is free*d
+and the result is left as a empty string.
+\fBTcl_ResetResult\fR also clears the error state managed by
+\fBTcl_AddErrorInfo\fR, \fBTcl_AddObjErrorInfo\fR,
+and \fBTcl_SetErrorCode\fR.
 .PP
-If \fIsourceInterp\fR and \fItargetInterp\fR are the same, nothing is done.
+\fBTcl_AppendResult\fR makes it easy to build up Tcl results in pieces.
+It takes each of its \fIresult\fR arguments and appends them in order
+to the current result associated with \fIinterp\fR.
+If the result is in its initialized empty state (e.g. a command procedure
+was just invoked or \fBTcl_ResetResult\fR was just called),
+then \fBTcl_AppendResult\fR sets the result to the concatenation of
+its \fIresult\fR arguments.
+\fBTcl_AppendResult\fR may be called repeatedly as additional pieces
+of the result are produced.
+\fBTcl_AppendResult\fR takes care of all the
+storage management issues associated with managing \fIinterp\fR's
+result, such as allocating a larger result area if necessary.
+It also manages conversion to and from the \fIresult\fR field of the
+\fIinterp\fR so as to handle backward-compatibility with old-style
+extensions.
+Any number of \fIresult\fR arguments may be passed in a single
+call; the last argument in the list must be (char *)NULL.
+.PP
+\fBTcl_TransferResult\fR transfers interpreter state from \fIsourceInterp\fR
+to \fItargetInterp\fR. The two interpreters must have been created in the
+same thread.  If \fIsourceInterp\fR and \fItargetInterp\fR are the same,
+nothing is done. Otherwise, \fBTcl_TransferResult\fR moves the result
+from \fIsourceInterp\fR to \fItargetInterp\fR, and resets the result
+in \fIsourceInterp\fR. It also moves the return options dictionary as
+controlled by the return code value \fIcode\fR in the same manner
+as \fBTcl_GetReturnOptions\fR.
 .SH "DEPRECATED INTERFACES"
 .SS "OLD STRING PROCEDURES"
 .PP
-The following procedures are deprecated since they manipulate the Tcl result as
-a string.  Procedures such as \fBTcl_SetObjResult\fR can be significantly more
-efficient.
-.PP
-\fBTcl_AppendElement\fR is like \fBTcl_AppendResult\fR, but it appends only one
-piece, and also appends that piece as a list item.
-\fBTcl_AppendElement\fR adds backslashes or braces as necessary to ensure that
-\fIelement\fR is properly formatted as a list item.  Under normal conditions,
-\fBTcl_AppendElement\fR adds a space character to \fIinterp\fR's result just
-before adding the new list element, so that the list elements in the result are
-properly separated.  However if the new list element is the first item in the
-list or sublist (i.e. \fIinterp\fR's current result is empty, or consists of
-the single character
+Use of the following procedures is deprecated
+since they manipulate the Tcl result as a string.
+Procedures such as \fBTcl_SetObjResult\fR
+that manipulate the result as a value
+can be significantly more efficient.
+.PP
+\fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in
+that it allows results to be built up in pieces.
+However, \fBTcl_AppendElement\fR takes only a single \fIelement\fR
+argument and it appends that argument to the current result
+as a proper Tcl list element.
+\fBTcl_AppendElement\fR adds backslashes or braces if necessary
+to ensure that \fIinterp\fR's result can be parsed as a list and that
+\fIelement\fR will be extracted as a single element.
+Under normal conditions, \fBTcl_AppendElement\fR will add a space
+character to \fIinterp\fR's result just before adding the new
+list element, so that the list elements in the result are properly
+separated.
+However if the new list element is the first in a list or sub-list
+(i.e. \fIinterp\fR's current result is empty, or consists of the
+single character
 .QW { ,
 or ends in the characters
 .QW " {" )
 then no space is added.
 .SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT"
 .PP
-\fIFreeProc\fR has the following type:
+\fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how
+the Tcl system is to manage the storage for the \fIresult\fR argument.
+If \fBTcl_SetResult\fR or \fBTcl_SetObjResult\fR are called
+at a time when \fIinterp\fR holds a string result,
+they do whatever is necessary to dispose of the old string result
+(see the \fBTcl_Interp\fR manual entry for details on this).
+.PP
+If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIresult\fR
+refers to an area of static storage that is guaranteed not to be
+modified until at least the next call to \fBTcl_Eval\fR.
+If \fIfreeProc\fR
+is \fBTCL_DYNAMIC\fR it means that \fIresult\fR was allocated with a call
+to \fBTcl_Alloc\fR and is now the property of the Tcl system.
+\fBTcl_SetResult\fR will arrange for the string's storage to be
+released by calling \fBTcl_Free\fR when it is no longer needed.
+If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIresult\fR
+points to an area of memory that is likely to be overwritten when
+\fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame).
+In this case \fBTcl_SetResult\fR will make a copy of the string in
+dynamically allocated storage and arrange for the copy to be the
+result for the current Tcl command.
+.PP
+If \fIfreeProc\fR is not one of the values \fBTCL_STATIC\fR,
+\fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address
+of a procedure that Tcl should call to free the string.
+This allows applications to use non-standard storage allocators.
+When Tcl no longer needs the storage for the string, it will
+call \fIfreeProc\fR. \fIFreeProc\fR should have arguments and
+result that match the type \fBTcl_FreeProc\fR:
 .PP
 .CS
 typedef void \fBTcl_FreeProc\fR(
         char *\fIblockPtr\fR);
 .CE
 .PP
-When \fIfreeProc\fR is called, \fIblockPtr\fR is the \fIresult\fR value passed
-to \fBTcl_SetResult\fR.
+When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to
+the value of \fIresult\fR passed to \fBTcl_SetResult\fR.
 
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The interpreter result is one of the main places that owns references to
+values, along with the bytecode execution stack, argument lists, variables,
+and the list and dictionary collection values.
+.PP
+\fBTcl_SetObjResult\fR takes a value with an arbitrary reference count
+\fI(specifically including zero)\fR and guarantees to increment the reference
+count. If code wishes to continue using the value after setting it as the
+result, it should add its own reference to it with \fBTcl_IncrRefCount\fR.
+.PP
+\fBTcl_GetObjResult\fR returns the current interpreter result value. This will
+have a reference count of at least 1. If the caller wishes to keep the
+interpreter result value, it should increment its reference count.
+.PP
+\fBTcl_GetStringResult\fR does not manipulate reference counts, but the string
+it returns is owned by (and has a lifetime controlled by) the current
+interpreter result value; it should be copied instead of being relied upon to
+persist after the next Tcl API call, as most Tcl operations can modify the
+interpreter result.
+.PP
+\fBTcl_SetResult\fR, \fBTcl_AppendResult\fR, \fBTcl_AppendResultVA\fR,
+\fBTcl_AppendElement\fR, and \fBTcl_ResetResult\fR all modify the interpreter
+result. They may cause the old interpreter result to have its reference count
+decremented and a new interpreter result to be allocated. After they have been
+called, the reference count of the interpreter result is guaranteed to be 1.
 .SH "SEE ALSO"
 Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp,
 Tcl_GetReturnOptions