Comments and renamings around the legacy fields for string results.

2 files changed, 45 insertions, 20 deletions

diff --git a/generic/tclInt.h b/generic/tclInt.h
index 7ed9bdf..90f283c 100644
--- a/generic/tclInt.h
+++ b/generic/tclInt.h
@@ -1799,31 +1799,33 @@ typedef struct AllocCache {
  */
 
 typedef struct Interp {
+
     /*
-     * Note: the first three fields must match exactly the fields in a
-     * Tcl_Interp struct (see tcl.h). If you change one, be sure to change the
-     * other.
-     *
-     * The interpreter's result is held in the objResultPtr field. This field
-     * holds the result's object value. The interpreter's result is always in
-     * objResultPtr. Programs should not access objResultPtr directly;
-     * instead, they should always get and set the result using procedures
-     * such as Tcl_SetObjResult, Tcl_GetObjResult, and Tcl_GetStringResult.
-     * See the SetResult man page for details.
+     * The first two fields were named "result" and "freeProc" in earlier
+     * versions of Tcl.  They are no longer used within Tcl, and are no
+     * longer available to be accessed by extensions.  However, they cannot
+     * be removed.  Why?  There is a deployed base of stub-enabled extensions
+     * that query the value of iPtr->stubTable.  For them to continue to work,
+     * the location of the field "stubTable" within the Interp struct cannot
+     * change.  The most robust way to assure that is to leave all fields up to
+     * that one undisturbed.
      */
 
-    char *unused3;
-    Tcl_FreeProc *unused4;
+    char *legacyResult;
+    Tcl_FreeProc *legacyFreeProc;
     int errorLine;		/* When TCL_ERROR is returned, this gives the
 				 * line number in the command where the error
 				 * occurred (1 means first line). */
     const struct TclStubs *stubTable;
-				/* Pointer to the exported Tcl stub table. On
-				 * previous versions of Tcl this is a pointer
-				 * to the objResultPtr or a pointer to a
-				 * buckets array in a hash table. We therefore
-				 * have to do some careful checking before we
-				 * can use this. */
+				/* Pointer to the exported Tcl stub table.  In
+				 * ancient pre-8.1 versions of Tcl this was a
+				 * pointer to the objResultPtr or a pointer to a
+				 * buckets array in a hash table. Deployed stubs
+				 * enabled extensions check for a NULL pointer value
+				 * and for a TCL_STUBS_MAGIC value to verify they
+				 * are not [load]ing into one of those pre-stubs
+				 * interps.
+				 */
 
     TclHandle handle;		/* Handle used to keep track of when this
 				 * interp is deleted. */
diff --git a/generic/tclStubLib.c b/generic/tclStubLib.c
index 9e9208d..35c7f09 100644
--- a/generic/tclStubLib.c
+++ b/generic/tclStubLib.c
@@ -41,9 +41,32 @@ HasStubSupport(
     if (iPtr->stubTable && (iPtr->stubTable->magic == TCL_STUB_MAGIC)) {
 	return iPtr->stubTable;
     }
-    iPtr->unused3
+
+    /*
+     * Either interp has no stubTable field, or its magic number has been
+     * changed, indicating a release of Tcl that no longer supports the
+     * stubs mechanism with which the extension has been prepared.  This
+     * either means interp comes from Tcl releases 7.5 - 8.0, when [load]
+     * of extensions was possible, but stubs were not yet in use, or it means
+     * interp come from some future release of Tcl where it has been necessary
+     * to stop supporting this particular stubs mechanism.  In either case,
+     * we can count on the fields legacyResult and legacyFreeProc existing
+     * (since they persist to maintain the struct offset fo stubTable; see
+     * tclInt.h comments.), and we can hope that [load] or any sensible
+     * successor will be able to reach into them to report the mismatch error
+     * message sensibly.
+     *
+     * For maximum compat support, even if only for the sake of reporting
+     * clean errors, rather than crashing, we assume the TCL_STUB_MAGIC
+     * value is changed only when absolutely necessary.  So long as the first
+     * slot in the stub table holds (some function compatible with) the routine
+     * Tcl_PkgRequireEx(), that routine can take care of verifying the version
+     * compatibility testing with all deployed
+     */
+
+    iPtr->legacyResult
 	    = "This interpreter does not support stubs-enabled extensions.";
-    iPtr->unused4 = TCL_STATIC;
+    iPtr->legacyFreeProc = TCL_STATIC;
     return NULL;
 }