From a75f6ac8ce9148d70852d4a6b749a42af19c6562 Mon Sep 17 00:00:00 2001 From: dgp Date: Sun, 5 Jan 2020 19:03:12 +0000 Subject: Fix documentation, comments, and argument names of Tcl_TransferResult(). --- doc/SetResult.3 | 24 +++++++++++++----------- generic/tcl.decls | 2 +- generic/tclDecls.h | 4 ++-- generic/tclResult.c | 32 +++++++++++++------------------- 4 files changed, 29 insertions(+), 33 deletions(-) diff --git a/doc/SetResult.3 b/doc/SetResult.3 index e5b81d7..ef6cceb 100644 --- a/doc/SetResult.3 +++ b/doc/SetResult.3 @@ -31,7 +31,7 @@ const char * \fBTcl_ResetResult\fR(\fIinterp\fR) .sp .VS 8.6 -\fBTcl_TransferResult\fR(\fIsourceInterp, result, targetInterp\fR) +\fBTcl_TransferResult\fR(\fIsourceInterp, code, targetInterp\fR) .VE 8.6 .sp \fBTcl_AppendElement\fR(\fIinterp, element\fR) @@ -58,16 +58,15 @@ An argument list which must have been initialized using \fBva_start\fR, and cleared using \fBva_end\fR. .AP Tcl_Interp *sourceInterp in .VS 8.6 -Interpreter that the result and error information should be copied from. +Interpreter that the result and return options should be transferred from. .VE 8.6 .AP Tcl_Interp *targetInterp in .VS 8.6 -Interpreter that the result and error information should be copied to. +Interpreter that the result and return options should be transferred to. .VE 8.6 -.AP int result in +.AP int code in .VS 8.6 -If \fBTCL_OK\fR, only copy the result. If \fBTCL_ERROR\fR, copy the error -information as well. +Return code value that controls transfer of return options. .VE 8.6 .BE .SH DESCRIPTION @@ -156,10 +155,12 @@ call; the last argument in the list must be a NULL pointer. instead of taking a variable number of arguments it takes an argument list. .PP .VS 8.6 -\fBTcl_TransferResult\fR moves a result from one interpreter to another, -optionally (dependent on the \fIresult\fR parameter) including the error -information dictionary as well. The interpreters must be in the same thread. -The source interpreter will have its result reset by this operation. +If \fIsourceInterp\fR and \fItargetInterp\fR are the same, this is a no-op. +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. The two +interpreters must have been created in the same thread. .VE 8.6 .SH "DEPRECATED INTERFACES" .SS "OLD STRING PROCEDURES" @@ -250,6 +251,7 @@ typedef void \fBTcl_FreeProc\fR( When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to the value of \fIresult\fR passed to \fBTcl_SetResult\fR. .SH "SEE ALSO" -Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp +Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp, +Tcl_GetReturnOptions .SH KEYWORDS append, command, element, list, value, result, return value, interpreter diff --git a/generic/tcl.decls b/generic/tcl.decls index c2a9c89..f37c0f6 100644 --- a/generic/tcl.decls +++ b/generic/tcl.decls @@ -2223,7 +2223,7 @@ declare 606 { # TIP#307 (move results between interpreters) dkf declare 607 { - void Tcl_TransferResult(Tcl_Interp *sourceInterp, int result, + void Tcl_TransferResult(Tcl_Interp *sourceInterp, int code, Tcl_Interp *targetInterp) } diff --git a/generic/tclDecls.h b/generic/tclDecls.h index 719cdf3..a49121a 100644 --- a/generic/tclDecls.h +++ b/generic/tclDecls.h @@ -1749,7 +1749,7 @@ EXTERN int Tcl_GetErrorLine(Tcl_Interp *interp); EXTERN void Tcl_SetErrorLine(Tcl_Interp *interp, int lineNum); /* 607 */ EXTERN void Tcl_TransferResult(Tcl_Interp *sourceInterp, - int result, Tcl_Interp *targetInterp); + int code, Tcl_Interp *targetInterp); /* 608 */ EXTERN int Tcl_InterpActive(Tcl_Interp *interp); /* 609 */ @@ -2477,7 +2477,7 @@ typedef struct TclStubs { int (*tcl_ParseArgsObjv) (Tcl_Interp *interp, const Tcl_ArgvInfo *argTable, int *objcPtr, Tcl_Obj *const *objv, Tcl_Obj ***remObjv); /* 604 */ int (*tcl_GetErrorLine) (Tcl_Interp *interp); /* 605 */ void (*tcl_SetErrorLine) (Tcl_Interp *interp, int lineNum); /* 606 */ - void (*tcl_TransferResult) (Tcl_Interp *sourceInterp, int result, Tcl_Interp *targetInterp); /* 607 */ + void (*tcl_TransferResult) (Tcl_Interp *sourceInterp, int code, Tcl_Interp *targetInterp); /* 607 */ int (*tcl_InterpActive) (Tcl_Interp *interp); /* 608 */ void (*tcl_BackgroundException) (Tcl_Interp *interp, int code); /* 609 */ int (*tcl_ZlibDeflate) (Tcl_Interp *interp, int format, Tcl_Obj *data, int level, Tcl_Obj *gzipHeaderDictObj); /* 610 */ diff --git a/generic/tclResult.c b/generic/tclResult.c index 9d0714c..bdb3912 100644 --- a/generic/tclResult.c +++ b/generic/tclResult.c @@ -1682,22 +1682,14 @@ Tcl_SetReturnOptions( * * Tcl_TransferResult -- * - * Copy the result (and error information) from one interp to another. + * Transfer the result (and error information) from one interp to another. * Used when one interp has caused another interp to evaluate a script * and then wants to transfer the results back to itself. * - * This routine copies the string reps of the result and error - * information. It does not simply increment the refcounts of the result - * and error information objects themselves. It is not legal to exchange - * objects between interps, because an object may be kept alive by one - * interp, but have an internal rep that is only valid while some other - * interp is alive. - * * Results: - * The target interp's result is set to a copy of the source interp's - * result. The source's errorInfo field may be transferred to the - * target's errorInfo field, and the source's errorCode field may be - * transferred to the target's errorCode field. + * The result of targetInterp is set to the result read from sourceInterp. + * The return options dictionary of sourceInterp is transferred to + * targetInterp as appropriate for the return code value code. * * Side effects: * None. @@ -1707,14 +1699,16 @@ Tcl_SetReturnOptions( void Tcl_TransferResult( - Tcl_Interp *sourceInterp, /* Interp whose result and error information + Tcl_Interp *sourceInterp, /* Interp whose result and return options * should be moved to the target interp. * After moving result, this interp's result * is reset. */ - int result, /* TCL_OK if just the result should be copied, - * TCL_ERROR if both the result and error - * information should be copied. */ - Tcl_Interp *targetInterp) /* Interp where result and error information + int code, /* The return code value active in + * sourceInterp. Controls how the return options + * dictionary is retrieved from sourceInterp, + * same as in Tcl_GetReturnOptions, to then be + * transferred to targetInterp. */ + Tcl_Interp *targetInterp) /* Interp where result and return options * should be stored. If source and target are * the same, nothing is done. */ { @@ -1725,7 +1719,7 @@ Tcl_TransferResult( return; } - if (result == TCL_OK && siPtr->returnOpts == NULL) { + if (code == TCL_OK && siPtr->returnOpts == NULL) { /* * Special optimization for the common case of normal command return * code and no explicit return options. @@ -1737,7 +1731,7 @@ Tcl_TransferResult( } } else { Tcl_SetReturnOptions(targetInterp, - Tcl_GetReturnOptions(sourceInterp, result)); + Tcl_GetReturnOptions(sourceInterp, code)); tiPtr->flags &= ~(ERR_ALREADY_LOGGED); } Tcl_SetObjResult(targetInterp, Tcl_GetObjResult(sourceInterp)); -- cgit v0.12