From a93db0866a458cfd4afff3157d2a1b525fcddccc Mon Sep 17 00:00:00 2001 From: pooryorick Date: Wed, 6 Nov 2019 20:41:58 +0000 Subject: Rewrite documentation of IO subsystem. --- generic/tcl.h | 249 ++++++++++++++++++++++---------------------------- generic/tclEncoding.c | 146 ++++++++++++++--------------- generic/tclFileName.c | 5 +- generic/tclPathObj.c | 197 ++++++++++++++++----------------------- unix/tclLoadDl.c | 7 +- unix/tclUnixFCmd.c | 110 +++++++++++----------- win/tclWinFile.c | 7 +- 7 files changed, 321 insertions(+), 400 deletions(-) diff --git a/generic/tcl.h b/generic/tcl.h index 571a9b9..c1187c6 100644 --- a/generic/tcl.h +++ b/generic/tcl.h @@ -1653,7 +1653,7 @@ typedef struct Tcl_FSVersion_ *Tcl_FSVersion; * struct Tcl_Filesystem: * * One such structure exists for each type (kind) of filesystem. It collects - * together in one place all the functions that are part of the specific + * together the functions that form the interface for a particulr the * filesystem. Tcl always accesses the filesystem through one of these * structures. * @@ -1668,147 +1668,119 @@ typedef struct Tcl_Filesystem { * compatibility can be assured. */ Tcl_FSVersion version; /* Version of the filesystem type. */ Tcl_FSPathInFilesystemProc *pathInFilesystemProc; - /* Function to check whether a path is in this + /* Determines whether the pathname is in this * filesystem. This is the most important * filesystem function. */ Tcl_FSDupInternalRepProc *dupInternalRepProc; - /* Function to duplicate internal fs rep. May - * be NULL (but then fs is less efficient). */ + /* Duplicates the internal handle of the node. + * If it is NULL, the filesystem is less + * performant. */ Tcl_FSFreeInternalRepProc *freeInternalRepProc; - /* Function to free internal fs rep. Must be - * implemented if internal representations - * need freeing, otherwise it can be NULL. */ + /* Frees the internal handle of the node. NULL + * only if there is no need to free resources + * used for the internal handle. */ Tcl_FSInternalToNormalizedProc *internalToNormalizedProc; - /* Function to convert internal representation - * to a normalized path. Only required if the - * fs creates pure path objects with no - * string/path representation. */ + /* Converts the internal handle to a normalized + * path. NULL if the filesystem creates nodes + * having no pathname. */ Tcl_FSCreateInternalRepProc *createInternalRepProc; - /* Function to create a filesystem-specific - * internal representation. May be NULL if - * paths have no internal representation, or - * if the Tcl_FSPathInFilesystemProc for this - * filesystem always immediately creates an - * internal representation for paths it - * accepts. */ + /* Creates an internal handle for a pathname. + * May be NULL if pathnames have no internal + * handle or if pathInFilesystemProc always + * immediately creates an internal + * representation for pathnames in the + * filesystem. */ Tcl_FSNormalizePathProc *normalizePathProc; - /* Function to normalize a path. Should be - * implemented for all filesystems which can - * have multiple string representations for - * the same path object. */ + /* Normalizes a path. Should be implemented if + * the filesystems supports multiple paths to + * the same node. */ Tcl_FSFilesystemPathTypeProc *filesystemPathTypeProc; - /* Function to determine the type of a path in - * this filesystem. May be NULL. */ + /* Determines the type of a path in this + * filesystem. May be NULL. */ Tcl_FSFilesystemSeparatorProc *filesystemSeparatorProc; - /* Function to return the separator - * character(s) for this filesystem. Must be - * implemented. */ - Tcl_FSStatProc *statProc; /* Function to process a 'Tcl_FSStat()' call. - * Must be implemented for any reasonable - * filesystem. */ - Tcl_FSAccessProc *accessProc; - /* Function to process a 'Tcl_FSAccess()' - * call. Must be implemented for any + /* Produces the separator character(s) for this + * filesystem. Must not be NULL. */ + Tcl_FSStatProc *statProc; /* Called by 'Tcl_FSStat()'. Provided by any * reasonable filesystem. */ + Tcl_FSAccessProc *accessProc; + /* Called by 'Tcl_FSAccess()'. Implemented by + * any reasonable filesystem. */ Tcl_FSOpenFileChannelProc *openFileChannelProc; - /* Function to process a - * 'Tcl_FSOpenFileChannel()' call. Must be - * implemented for any reasonable - * filesystem. */ + /* Called by 'Tcl_FSOpenFileChannel()'. + * Provided by any reasonable filesystem. */ Tcl_FSMatchInDirectoryProc *matchInDirectoryProc; - /* Function to process a - * 'Tcl_FSMatchInDirectory()'. If not - * implemented, then glob and recursive copy - * functionality will be lacking in the - * filesystem. */ - Tcl_FSUtimeProc *utimeProc; /* Function to process a 'Tcl_FSUtime()' call. - * Required to allow setting (not reading) of - * times with 'file mtime', 'file atime' and - * the open-r/open-w/fcopy implementation of - * 'file copy'. */ - Tcl_FSLinkProc *linkProc; /* Function to process a 'Tcl_FSLink()' call. - * Should be implemented only if the - * filesystem supports links (reading or - * creating). */ + /* Called by 'Tcl_FSMatchInDirectory()'. NULL + * if the filesystem does not support glob or + * recursive copy. */ + Tcl_FSUtimeProc *utimeProc; /* Called by 'Tcl_FSUtime()', by 'file + * mtime' to set (not read) times, 'file + * atime', and the open-r/open-w/fcopy variant + * of 'file copy'. */ + Tcl_FSLinkProc *linkProc; /* Called by 'Tcl_FSLink()'. NULL if reading or + * creating links is not supported. */ Tcl_FSListVolumesProc *listVolumesProc; - /* Function to list any filesystem volumes - * added by this filesystem. Should be - * implemented only if the filesystem adds - * volumes at the head of the filesystem. */ + /* Lists filesystem volumes added by this + * filesystem. NULL if the filesystem does not + * use volumes. */ Tcl_FSFileAttrStringsProc *fileAttrStringsProc; - /* Function to list all attributes strings - * which are valid for this filesystem. If not - * implemented the filesystem will not support - * the 'file attributes' command. This allows - * arbitrary additional information to be - * attached to files in the filesystem. */ + /* List all valid attributes strings. NULL if + * the filesystem does not support the 'file + * attributes' command. Can be used to attach + * arbitrary additional data to files in a + * filesystem. */ Tcl_FSFileAttrsGetProc *fileAttrsGetProc; - /* Function to process a - * 'Tcl_FSFileAttrsGet()' call, used by 'file - * attributes'. */ + /* Called by 'Tcl_FSFileAttrsGet()' and by + * 'file attributes'. */ Tcl_FSFileAttrsSetProc *fileAttrsSetProc; - /* Function to process a - * 'Tcl_FSFileAttrsSet()' call, used by 'file - * attributes'. */ + /* Called by 'Tcl_FSFileAttrsSet()' and by + * 'file attributes'. */ Tcl_FSCreateDirectoryProc *createDirectoryProc; - /* Function to process a - * 'Tcl_FSCreateDirectory()' call. Should be - * implemented unless the FS is read-only. */ + /* Called by 'Tcl_FSCreateDirectory()'. May be + * NULL if the filesystem is read-only. */ Tcl_FSRemoveDirectoryProc *removeDirectoryProc; - /* Function to process a - * 'Tcl_FSRemoveDirectory()' call. Should be - * implemented unless the FS is read-only. */ + /* Called by 'Tcl_FSRemoveDirectory()'. May be + * NULL if the filesystem is read-only. */ Tcl_FSDeleteFileProc *deleteFileProc; - /* Function to process a 'Tcl_FSDeleteFile()' - * call. Should be implemented unless the FS - * is read-only. */ + /* Called by 'Tcl_FSDeleteFile()' May be NULL + * if the filesystem is is read-only. */ Tcl_FSCopyFileProc *copyFileProc; - /* Function to process a 'Tcl_FSCopyFile()' - * call. If not implemented Tcl will fall back - * on open-r, open-w and fcopy as a copying - * mechanism, for copying actions initiated in - * Tcl (not C). */ + /* Called by 'Tcl_FSCopyFile()'. If NULL, for + * a copy operation at the script level (not + * C) Tcl uses open-r, open-w and fcopy. */ Tcl_FSRenameFileProc *renameFileProc; - /* Function to process a 'Tcl_FSRenameFile()' - * call. If not implemented, Tcl will fall - * back on a copy and delete mechanism, for - * rename actions initiated in Tcl (not C). */ + /* Called by 'Tcl_FSRenameFile()'. If NULL, for + * a rename operation at the script level (not + * C) Tcl performs a copy operation followed + * by a delete operation. */ Tcl_FSCopyDirectoryProc *copyDirectoryProc; - /* Function to process a - * 'Tcl_FSCopyDirectory()' call. If not - * implemented, Tcl will fall back on a - * recursive create-dir, file copy mechanism, - * for copying actions initiated in Tcl (not - * C). */ - Tcl_FSLstatProc *lstatProc; /* Function to process a 'Tcl_FSLstat()' call. - * If not implemented, Tcl will attempt to use - * the 'statProc' defined above instead. */ + /* Called by 'Tcl_FSCopyDirectory()'. If NULL, + * for a copy operation at the script level + * (not C) Tcl recursively creates directories + * and copies files. */ + Tcl_FSLstatProc *lstatProc; /* Called by 'Tcl_FSLstat()'. If NULL, Tcl + * attempts to use 'statProc' instead. */ Tcl_FSLoadFileProc *loadFileProc; - /* Function to process a 'Tcl_FSLoadFile()' - * call. If not implemented, Tcl will fall - * back on a copy to native-temp followed by a - * Tcl_FSLoadFile on that temporary copy. */ + /* Called by 'Tcl_FSLoadFile()'. If NULL, Tcl + * performs a copy to a temporary file in the + * native filesystem and then calls + * Tcl_FSLoadFile() on that temporary copy. */ Tcl_FSGetCwdProc *getCwdProc; - /* Function to process a 'Tcl_FSGetCwd()' - * call. Most filesystems need not implement - * this. It will usually only be called once, - * if 'getcwd' is called before 'chdir'. May - * be NULL. */ - Tcl_FSChdirProc *chdirProc; /* Function to process a 'Tcl_FSChdir()' call. - * If filesystems do not implement this, it - * will be emulated by a series of directory - * access checks. Otherwise, virtual - * filesystems which do implement it need only - * respond with a positive return result if - * the dirName is a valid directory in their - * filesystem. They need not remember the - * result, since that will be automatically - * remembered for use by GetCwd. Real - * filesystems should carry out the correct - * action (i.e. call the correct system - * 'chdir' api). If not implemented, then 'cd' - * and 'pwd' will fail inside the - * filesystem. */ + /* Called by 'Tcl_FSGetCwd()'. Normally NULL. + * Usually only called once: If 'getcwd' is + * called before 'chdir' is ever called. */ + Tcl_FSChdirProc *chdirProc; /* Called by 'Tcl_FSChdir()'. For a virtual + * filesystem, chdirProc just returns zero + * (success) if the pathname is a valid + * directory, and some other value otherwise. + * For A real filesystem, chdirProc performs + * the correct action, e.g. calls the system + * 'chdir' function. If not implemented, then + * 'cd' and 'pwd' fail for a pathname in this + * filesystem. On success Tcl stores the + * pathname for use by GetCwd. If NULL, Tcl + * performs records the pathname as the new + * current directory if it passes a series of + * directory access checks. */ } Tcl_Filesystem; /* @@ -2069,29 +2041,28 @@ typedef struct Tcl_EncodingType { * reset to an initial state. If the source * buffer contains the entire input stream to be * converted, this flag should be set. - * TCL_ENCODING_STOPONERROR - If set, then the converter will return - * immediately upon encountering an invalid byte - * sequence or a source character that has no - * mapping in the target encoding. If clear, then - * the converter will skip the problem, - * substituting one or more "close" characters in - * the destination buffer and then continue to + * TCL_ENCODING_STOPONERROR - If set, the converter returns immediately upon + * encountering an invalid byte sequence or a + * source character that has no mapping in the + * target encoding. If clear, the converter + * substitues the problematic character(s) with + * one or more "close" characters in the + * destination buffer and then continues to * convert the source. - * TCL_ENCODING_NO_TERMINATE - If set, Tcl_ExternalToUtf will not append a - * terminating NUL byte. Knowing that it will - * not need space to do so, it will fill all - * dstLen bytes with encoded UTF-8 content, as - * other circumstances permit. If clear, the - * default behavior is to reserve a byte in - * the dst space for NUL termination, and to - * append the NUL byte. + * TCL_ENCODING_NO_TERMINATE - If set, Tcl_ExternalToUtf does not append a + * terminating NUL byte. Since it does not need + * an extra byte for a terminating NUL, it fills + * all dstLen bytes with encoded UTF-8 content if + * needed. If clear, a byte is reserved in the + * dst space for NUL termination, and a + * terminating NUL is appended. * TCL_ENCODING_CHAR_LIMIT - If set and dstCharsPtr is not NULL, then - * Tcl_ExternalToUtf takes the initial value - * of *dstCharsPtr is taken as a limit of the - * maximum number of chars to produce in the - * encoded UTF-8 content. Otherwise, the - * number of chars produced is controlled only - * by other limiting factors. + * Tcl_ExternalToUtf takes the initial value of + * *dstCharsPtr as a limit of the maximum number + * of chars to produce in the encoded UTF-8 + * content. Otherwise, the number of chars + * produced is controlled only by other limiting + * factors. */ #define TCL_ENCODING_START 0x01 diff --git a/generic/tclEncoding.c b/generic/tclEncoding.c index 0ec0649..430f705 100644 --- a/generic/tclEncoding.c +++ b/generic/tclEncoding.c @@ -83,7 +83,7 @@ typedef struct { } TableEncodingData; /* - * The following structures is the clientData for a dynamically-loaded, + * Each of the following structures is the clientData for a dynamically-loaded * escape-driven encoding that is itself comprised of other simpler encodings. * An example is "iso-2022-jp", which uses escape sequences to switch between * ascii, jis0208, jis0212, gb2312, and ksc5601. Note that "escape-driven" @@ -117,8 +117,8 @@ typedef struct { * 0. */ int numSubTables; /* Length of following array. */ EscapeSubTable subTables[1];/* Information about each EscapeSubTable used - * by this encoding type. The actual size will - * be as large as necessary to hold all + * by this encoding type. The actual size is + * as large as necessary to hold all * EscapeSubTables. */ } EscapeEncodingData; @@ -156,7 +156,7 @@ static ProcessGlobalValue encodingFileMap = { * A list of directories making up the "library path". Historically this * search path has served many uses, but the only one remaining is a base for * the encodingSearchPath above. If the application does not explicitly set - * the encodingSearchPath, then it will be initialized by appending /encoding + * the encodingSearchPath, then it is initialized by appending /encoding * to each directory in this "libraryPath". */ @@ -177,7 +177,7 @@ TCL_DECLARE_MUTEX(encodingMutex) /* * The following are used to hold the default and current system encodings. * If NULL is passed to one of the conversion routines, the current setting of - * the system encoding will be used to perform the conversion. + * the system encoding is used to perform the conversion. */ static Tcl_Encoding defaultEncoding = NULL; @@ -451,9 +451,8 @@ TclGetLibraryPath(void) * Keeps the per-thread copy of the library path current with changes to * the global copy. * - * NOTE: this routine returns void, so there's no way to report the error - * that searchPath is not a valid list. In that case, this routine will - * silently do nothing. + * Since the result of this routine is void, if searchPath is not a valid + * list this routine silently does nothing. * *---------------------------------------------------------------------- */ @@ -475,17 +474,16 @@ TclSetLibraryPath( * * FillEncodingFileMap -- * - * Called to bring the encoding file map in sync with the current value + * Called to update the encoding file map with the current value * of the encoding search path. * - * Scan the directories on the encoding search path, find the *.enc - * files, and store the found pathnames in a map associated with the - * encoding name. + * Finds *.end files in the directories on the encoding search path and + * stores the found pathnames in a map associated with the encoding name. * - * In particular, if $dir is on the encoding search path, and the file - * $dir/foo.enc is found, then store a "foo" -> $dir entry in the map. - * Later, any need for the "foo" encoding will quickly * be able to - * construct the $dir/foo.enc pathname for reading the encoding data. + * If $dir is on the encoding search path and the file $dir/foo.enc is + * found, stores a "foo" -> $dir entry in the map. if the "foo" encoding + * is needed later, the $dir/foo.enc name can be quickly constructed in + * order to read the encoding data. * * Results: * None. @@ -584,9 +582,9 @@ TclInitEncodingSubsystem(void) Tcl_MutexUnlock(&encodingMutex); /* - * Create a few initial encodings. Note that the UTF-8 to UTF-8 - * translation is not a no-op, because it will turn a stream of improperly - * formed UTF-8 into a properly formed stream. + * Create a few initial encodings. UTF-8 to UTF-8 translation is not a + * no-op because it turns a stream of improperly formed UTF-8 into a + * properly formed stream. */ type.encodingName = NULL; @@ -806,11 +804,7 @@ Tcl_SetDefaultEncodingDir( * interp was NULL. * * Side effects: - * The new encoding type is entered into a table visible to all - * interpreters, keyed off the encoding's name. For each call to this - * function, there should eventually be a call to Tcl_FreeEncoding, so - * that the database can be cleaned up when encodings aren't needed - * anymore. + * LoadEncodingFile is called if necessary. * *------------------------------------------------------------------------- */ @@ -848,15 +842,15 @@ Tcl_GetEncoding( * * Tcl_FreeEncoding -- * - * This function is called to release an encoding allocated by - * Tcl_CreateEncoding() or Tcl_GetEncoding(). + * Releases an encoding allocated by Tcl_CreateEncoding() or + * Tcl_GetEncoding(). * * Results: * None. * * Side effects: * The reference count associated with the encoding is decremented and - * the encoding may be deleted if nothing is using it anymore. + * the encoding is deleted if nothing is using it anymore. * *--------------------------------------------------------------------------- */ @@ -875,13 +869,14 @@ Tcl_FreeEncoding( * * FreeEncoding -- * - * This function is called to release an encoding by functions that - * already have the encodingMutex. + * Decrements the reference count of an encoding. The caller must hold + * encodingMutes. * * Results: * None. * * Side effects: + * Releases the resource for an encoding if it is now unused. * The reference count associated with the encoding is decremented and * the encoding may be deleted if nothing is using it anymore. * @@ -1069,23 +1064,22 @@ Tcl_SetSystemEncoding( * * Tcl_CreateEncoding -- * - * This function is called to define a new encoding and the functions - * that are used to convert between the specified encoding and Unicode. + * Defines a new encoding, along with the functions that are used to + * convert to and from Unicode. * * Results: * Returns a token that represents the encoding. If an encoding with the * same name already existed, the old encoding token remains valid and - * continues to behave as it used to, and will eventually be garbage - * collected when the last reference to it goes away. Any subsequent - * calls to Tcl_GetEncoding with the specified name will retrieve the - * most recent encoding token. + * continues to behave as it used to, and is eventually garbage collected + * when the last reference to it goes away. Any subsequent calls to + * Tcl_GetEncoding with the specified name retrieve the most recent + * encoding token. * * Side effects: - * The new encoding type is entered into a table visible to all - * interpreters, keyed off the encoding's name. For each call to this - * function, there should eventually be a call to Tcl_FreeEncoding, so - * that the database can be cleaned up when encodings aren't needed - * anymore. + * A new record having the name of the encoding is entered into a table of + * encodings visible to all interpreters. For each call to this function, + * there should eventually be a call to Tcl_FreeEncoding, which cleans + * deletes the record in the table when an encoding is no longer needed. * *--------------------------------------------------------------------------- */ @@ -1332,10 +1326,9 @@ Tcl_ExternalToUtf( * * Tcl_UtfToExternalDString -- * - * Convert a source buffer from UTF-8 into the specified encoding. If any + * Convert a source buffer from UTF-8 to the specified encoding. If any * of the bytes in the source buffer are invalid or cannot be represented - * in the target encoding, a default fallback character will be - * substituted. + * in the target encoding, a default fallback character is substituted. * * Results: * The converted bytes are stored in the DString, which is then NULL @@ -1646,13 +1639,13 @@ OpenEncodingFileChannel( * the data. * * Results: - * The return value is the newly loaded Encoding, or NULL if the file - * didn't exist of was in the incorrect format. If NULL was returned, an - * error message is left in interp's result object, unless interp was - * NULL. + * The return value is the newly loaded Tcl_Encoding or NULL if the file + * didn't exist or could not be processed. If NULL is returned and interp + * is not NULL, an error message is left in interp's result object. * * Side effects: - * File read from disk. + * A corresponding encoding file might be read from persistent storage, in + * which case LoadTableEncoding is called. * *--------------------------------------------------------------------------- */ @@ -1660,8 +1653,8 @@ OpenEncodingFileChannel( static Tcl_Encoding LoadEncodingFile( Tcl_Interp *interp, /* Interp for error reporting, if not NULL. */ - const char *name) /* The name of the encoding file on disk and - * also the name for new encoding. */ + const char *name) /* The name of both the encoding file + * and the new encoding. */ { Tcl_Channel chan = NULL; Tcl_Encoding encoding = NULL; @@ -1715,27 +1708,27 @@ LoadEncodingFile( * * LoadTableEncoding -- * - * Helper function for LoadEncodingTable(). Loads a table to that - * converts between Unicode and some other encoding and creates an - * encoding (using a TableEncoding structure) from that information. + * Helper function for LoadEncodingFile(). Creates a Tcl_EncodingType + * structure along with its corresponding TableEncodingData structure, and + * passes it to Tcl_Createncoding. * - * File contains binary data, but begins with a marker to indicate - * byte-ordering, so that same binary file can be read on either endian - * platforms. + * The file contains binary data but begins with a marker to indicate + * byte-ordering so a single binary file can be read on big or + * little-endian systems. * * Results: - * The return value is the new encoding, or NULL if the encoding could - * not be created (because the file contained invalid data). + * Returns the new Tcl_Encoding, or NULL if it could could + * not be created because the file contained invalid data. * * Side effects: - * None. + * See Tcl_CreateEncoding(). * *------------------------------------------------------------------------- */ static Tcl_Encoding LoadTableEncoding( - const char *name, /* Name for new encoding. */ + const char *name, /* Name of the new encoding. */ int type, /* Type of encoding (ENCODING_?????). */ Tcl_Channel chan) /* File containing new encoding. */ { @@ -1852,10 +1845,10 @@ LoadTableEncoding( } /* - * Invert toUnicode array to produce the fromUnicode array. Performs a + * Invert the toUnicode array to produce the fromUnicode array. Performs a * single malloc to get the memory for the array and all the pages needed - * by the array. While reading in the toUnicode array, we remembered what - * pages that would be needed for the fromUnicode array. + * by the array. While reading in the toUnicode array remember what + * pages are needed for the fromUnicode array. */ if (symbol) { @@ -1894,8 +1887,8 @@ LoadTableEncoding( if (type == ENCODING_MULTIBYTE) { /* * If multibyte encodings don't have a backslash character, define - * one. Otherwise, on Windows, native file names won't work because - * the backslash in the file name will map to the unknown character + * one. Otherwise, on Windows, native file names don't work because + * the backslash in the file name maps to the unknown character * (question mark) when converting from UTF-8 to external encoding. */ @@ -1907,13 +1900,13 @@ LoadTableEncoding( } if (symbol) { /* - * Make a special symbol encoding that not only maps the symbol - * characters from their Unicode code points down into page 0, but - * also ensure that the characters on page 0 map to themselves. This - * is so that a symbol font can be used to display a simple string - * like "abcd" and have alpha, beta, chi, delta show up, rather than - * have "unknown" chars show up because strictly speaking the symbol - * font doesn't have glyphs for those low ASCII chars. + * Make a special symbol encoding that maps each symbol character from + * its Unicode code point down into page 0, and also ensure that each + * characters on page 0 maps to itself so that a symbol font can be + * used to display a simple string like "abcd" and have alpha, beta, + * chi, delta show up, rather than have "unknown" chars show up because + * strictly speaking the symbol font doesn't have glyphs for those low + * ASCII chars. */ page = dataPtr->fromUnicode[0]; @@ -1960,7 +1953,7 @@ LoadTableEncoding( } /* - * Read lines from the encoding until EOF. + * Read lines until EOF. */ for (TclDStringClear(&lineString); @@ -2037,7 +2030,7 @@ LoadTableEncoding( static Tcl_Encoding LoadEscapeEncoding( - const char *name, /* Name for new encoding. */ + const char *name, /* Name of the new encoding. */ Tcl_Channel chan) /* File containing new encoding. */ { int i; @@ -3661,14 +3654,13 @@ EscapeFromUtfProc( * * EscapeFreeProc -- * - * This function is invoked when an EscapeEncodingData encoding is - * deleted. It deletes the memory used by the encoding. + * Frees resources used by the encoding. * * Results: * None. * * Side effects: - * Memory freed. + * Memory is freed. * *--------------------------------------------------------------------------- */ diff --git a/generic/tclFileName.c b/generic/tclFileName.c index 3419d7c..834eef7 100644 --- a/generic/tclFileName.c +++ b/generic/tclFileName.c @@ -1680,9 +1680,8 @@ Tcl_GlobObjCmd( * * TclGlob -- * - * This procedure prepares arguments for the DoGlob call. It sets the - * separator string based on the platform, performs * tilde substitution, - * and calls DoGlob. + * Sets the separator string based on the platform, performs tilde + * substitution, and calls DoGlob. * * The interpreter's result, on entry to this function, must be a valid * Tcl list (e.g. it could be empty), since we will lappend any new diff --git a/generic/tclPathObj.c b/generic/tclPathObj.c index f7f1c8f..660db03 100644 --- a/generic/tclPathObj.c +++ b/generic/tclPathObj.c @@ -47,37 +47,21 @@ static const Tcl_ObjType fsPathType = { /* * struct FsPath -- * - * Internal representation of a Tcl_Obj of "path" type. This can be used to - * represent relative or absolute paths, and has certain optimisations when - * used to represent paths which are already normalized and absolute. - * - * There are two cases, with the first being the most common: - * - * (i) flags == 0, => Ordinary path. - * - * translatedPathPtr contains the translated path. If it is NULL then the path - * is pure normalized. cwdPtr is null for an absolute path, and non-null for a - * relative path (unless the cwd has never been set, in which case the cwdPtr - * may also be null for a relative path). - * - * (ii) flags != 0, => Special path, see TclNewFSPathObj - * - * Now, this is a path like 'file join $dir $tail' where, cwdPtr is the $dir - * and normPathPtr is the $tail. - * + * Internal representation of a Tcl_Obj of fsPathType */ typedef struct FsPath { - Tcl_Obj *translatedPathPtr; /* Name without any ~user sequences. If this - * is NULL, then this is a pure normalized, - * absolute path object, in which the parent - * Tcl_Obj's string rep is already both - * translated and normalized. */ - Tcl_Obj *normPathPtr; /* Normalized absolute path, without ., .. or - * ~user sequences. */ - Tcl_Obj *cwdPtr; /* If null, path is absolute, else this points - * to the cwd object used for this path. We - * have a refCount on the object. */ + Tcl_Obj *translatedPathPtr; /* If the path has been normalized (flags == + * 0), this is NULL. Otherwise it is a path + * in which any ~user sequences have been + * translated away. */ + Tcl_Obj *normPathPtr; /* If the path has been normalized (flags == + * 0), this is an absolute path without ., .. + * or ~user components. Otherwise it is a + * path, possibly absolute, to normalize + * relative to cwdPtr. */ + Tcl_Obj *cwdPtr; /* If NULL, either translatedPtr exists or + * normPathPtr exists and is absolute. */ int flags; /* Flags to describe interpretation - see * below. */ ClientData nativePathPtr; /* Native representation of this path, which @@ -131,17 +115,17 @@ typedef struct FsPath { * pathPtr may have a refCount of zero, or may be a shared object. * * Results: - * The result is returned in a Tcl_Obj with a refCount of 1, which is - * therefore owned by the caller. It must be freed (with - * Tcl_DecrRefCount) by the caller when no longer needed. + * The result is returned in a Tcl_Obj with a refCount already + * incremented, which gives the caller ownership of it. The caller must + * arrange for Tcl_DecRefCount to be called when the object is no-longer + * needed. * * Side effects: * None (beyond the memory allocation for the result). * * Special note: - * This code was originally based on code from Matt Newman and - * Jean-Claude Wippler, but has since been totally rewritten by Vince - * Darley to deal with symbolic links. + * Originally based on code from Matt Newman and Jean-Claude Wippler. + * Totally rewritten later by Vince Darley to handle symbolic links. * *--------------------------------------------------------------------------- */ @@ -710,9 +694,8 @@ TclPathPart( } /* - * The behaviour we want here is slightly different to the standard * Tcl_FSSplitPath in the handling of home directories; - * Tcl_FSSplitPath preserves the "~" while this code computes the + * Tcl_FSSplitPath preserves the "~", but this code computes the * actual full path name, if we had just a single component. */ @@ -871,7 +854,7 @@ TclJoinPath( * could expand that in the future. * * Bugfix [a47641a0]. TclNewFSPathObj requires first argument - * to be an absolute path. Added a check for that elt is absolute. + * to be an absolute path. Added a check to ensure that elt is absolute. */ if ((eltIr) @@ -1508,7 +1491,7 @@ MakePathFromNormalized( * * Tcl_FSNewNativePath -- * - * This function performs the something like the reverse of the usual + * Performs the something like the reverse of the usual * obj->path->nativerep conversions. If some code retrieves a path in * native form (from, e.g. readlink or a native dialog), and that path is * to be used at the Tcl level, then calling this function is an @@ -1571,16 +1554,18 @@ Tcl_FSNewNativePath( * * Tcl_FSGetTranslatedPath -- * - * This function attempts to extract the translated path from the given + * Attempts to extract the translated path from the given * Tcl_Obj. If the translation succeeds (i.e. the object is a valid - * path), then it is returned. Otherwise NULL will be returned, and an - * error message may be left in the interpreter (if it is non-NULL) + * path), then it is returned. Otherwise NULL is returned and an + * error message may be left in the interpreter if it is not NULL. * * Results: - * NULL or a valid Tcl_Obj pointer. + * A Tcl_Obj pointer or NULL. * * Side effects: - * Only those of 'Tcl_FSConvertToPathType' + * pathPtr is converted to fsPathType if necessary. + * + * FsPath members are modified as needed. * *--------------------------------------------------------------------------- */ @@ -1598,7 +1583,12 @@ Tcl_FSGetTranslatedPath( } srcFsPathPtr = PATHOBJ(pathPtr); if (srcFsPathPtr->translatedPathPtr == NULL) { - if (PATHFLAGS(pathPtr) != 0) { + if (PATHFLAGS(pathPtr) == 0) { + /* + * Path is already normalized + */ + retObj = srcFsPathPtr->normPathPtr; + } else { /* * We lack a translated path result, but we have a directory * (cwdPtr) and a tail (normPathPtr), and if we join the @@ -1625,14 +1615,6 @@ Tcl_FSGetTranslatedPath( srcFsPathPtr->filesystemEpoch = 0; } Tcl_DecrRefCount(translatedCwdPtr); - } else { - /* - * It is a pure absolute, normalized path object. This is - * something like being a 'pure list'. The object's string, - * translatedPath and normalizedPath are all identical. - */ - - retObj = srcFsPathPtr->normPathPtr; } } else { /* @@ -1800,11 +1782,6 @@ Tcl_FSGetNormalizedPath( TclDecrRefCount(fsPathPtr->normPathPtr); fsPathPtr->normPathPtr = copy; - /* - * That's our reference to copy used. - */ - copy = NULL; - TclDecrRefCount(dir); TclDecrRefCount(origDir); } else { @@ -1813,10 +1790,6 @@ Tcl_FSGetNormalizedPath( TclDecrRefCount(fsPathPtr->normPathPtr); fsPathPtr->normPathPtr = copy; - /* - * That's our reference to copy used. - */ - copy = NULL; TclDecrRefCount(dir); } PATHFLAGS(pathPtr) = 0; @@ -1857,7 +1830,7 @@ Tcl_FSGetNormalizedPath( Tcl_Obj *useThisCwd = NULL; /* - * Since normPathPtr is NULL, but this is a valid path object, we know + * Since normPathPtr is NULL but this is a valid path object, we know * that the translatedPathPtr cannot be NULL. */ @@ -1957,19 +1930,23 @@ Tcl_FSGetNormalizedPath( * * Tcl_FSGetInternalRep -- * - * Extract the internal representation of a given path object, in the - * given filesystem. If the path object belongs to a different - * filesystem, we return NULL. + * Produces a native representation of a given path object in the given + * filesystem. * - * If the internal representation is currently NULL, we attempt to - * generate it, by calling the filesystem's - * 'Tcl_FSCreateInternalRepProc'. + * In the future it might be desirable to have separate versions + * of this function with different signatures, for example + * Tcl_FSGetNativeWinPath, Tcl_FSGetNativeUnixPath etc. Right now, since + * native paths are all string based, we use just one function. * * Results: - * NULL or a valid internal representation. + * + * The native handle for the path, or NULL if the path is not handled by + * the given filesystem * * Side effects: - * An attempt may be made to convert the object. + * + * Tcl_FSCreateInternalRepProc if needed to produce the native + * handle, which is then stored in the internal representation of pathPtr. * *--------------------------------------------------------------------------- */ @@ -1987,49 +1964,36 @@ Tcl_FSGetInternalRep( srcFsPathPtr = PATHOBJ(pathPtr); /* - * We will only return the native representation for the caller's - * filesystem. Otherwise we will simply return NULL. This means that there - * must be a unique bi-directional mapping between paths and filesystems, - * and that this mapping will not allow 'remapped' files -- files which - * are in one filesystem but mapped into another. Another way of putting - * this is that 'stacked' filesystems are not allowed. We recognise that - * this is a potentially useful feature for the future. + * Currently there must be a unique bi-directional mapping between a path + * and a filesystem, and therefore there is no way to "remap" a file, i.e., + * to map a file in one filesystem into another. Another way of putting + * this is that 'stacked' filesystems are not allowed. It could be useful + * in the future to redesign the system to allow that. * * Even something simple like a 'pass through' filesystem which logs all * activity and passes the calls onto the native system would be nice, but - * not easily achievable with the current implementation. + * not currently easily achievable. */ if (srcFsPathPtr->fsPtr == NULL) { - /* - * This only usually happens in wrappers like TclpStat which create a - * string object and pass it to TclpObjStat. Code which calls the - * Tcl_FS.. functions should always have a filesystem already set. - * Whether this code path is legal or not depends on whether we decide - * to allow external code to call the native filesystem directly. It - * is at least safer to allow this sub-optimal routing. - */ - Tcl_FSGetFileSystemForPath(pathPtr); - /* - * If we fail through here, then the path is probably not a valid path - * in the filesystsem, and is most likely to be a use of the empty - * path "" via a direct call to one of the objectified interfaces - * (e.g. from the Tcl testsuite). - */ - srcFsPathPtr = PATHOBJ(pathPtr); if (srcFsPathPtr->fsPtr == NULL) { + /* + * The path is probably not a valid path in the filesystsem, and is + * most likely to be a use of the empty path "" via a direct call + * to one of the objectified interfaces (e.g. from the Tcl + * testsuite). + */ return NULL; } } /* - * There is still one possibility we should consider; if the file belongs - * to a different filesystem, perhaps it is actually linked through to a - * file in our own filesystem which we do care about. The way we can check - * for this is we ask what filesystem this path belongs to. + * If the file belongs to a different filesystem, perhaps it is actually + * linked through to a file in the given filesystem. Check this by + * inspecting the filesystem associated with the given path. */ if (fsPtr != srcFsPathPtr->fsPtr) { @@ -2064,15 +2028,15 @@ Tcl_FSGetInternalRep( * * TclFSEnsureEpochOk -- * - * This will ensure the pathPtr is up to date and can be converted into a - * "path" type, and that we are able to generate a complete normalized - * path which is used to determine the filesystem match. + * Ensure that the path is a valid path, and that it has a + * fsPathType internal representation that is not stale. * * Results: - * Standard Tcl return code. + * A standard Tcl return code. * * Side effects: - * An attempt may be made to convert the object. + * The internal representation of fsPtrPtr is converted to fsPathType if + * possible. * *--------------------------------------------------------------------------- */ @@ -2090,14 +2054,11 @@ TclFSEnsureEpochOk( srcFsPathPtr = PATHOBJ(pathPtr); - /* - * Check if the filesystem has changed in some way since this object's - * internal representation was calculated. - */ - if (!TclFSEpochOk(srcFsPathPtr->filesystemEpoch)) { /* - * We have to discard the stale representation and recalculate it. + * The filesystem has changed in some way since the internal + * representation for this object was calculated. Discard the stale + * representation and recalculate it. */ TclGetString(pathPtr); @@ -2108,11 +2069,10 @@ TclFSEnsureEpochOk( srcFsPathPtr = PATHOBJ(pathPtr); } - /* - * Check whether the object is already assigned to a fs. - */ - if (srcFsPathPtr->fsPtr != NULL) { + /* + * There is already a filesystem assigned to this path. + */ *fsPtrPtr = srcFsPathPtr->fsPtr; } return TCL_OK; @@ -2220,11 +2180,12 @@ Tcl_FSEqualPaths( * * SetFsPathFromAny -- * - * This function tries to convert the given Tcl_Obj to a valid Tcl path - * type. + * Attempt to convert the internal representation of pathPtr to + * fsPathType. * - * The filename may begin with "~" (to indicate current user's home - * directory) or "~" (to indicate any user's home directory). + * A tilde ("~") character at the beginnig of the filename indicates the + * current user's home directory, and "~" indicates a particular + * user's directory. * * Results: * Standard Tcl error code. @@ -2308,7 +2269,7 @@ SetFsPathFromAny( Tcl_DStringFree(&dirString); } else { /* - * We have a user name '~user' + * There is a '~user' */ const char *expandedUser; diff --git a/unix/tclLoadDl.c b/unix/tclLoadDl.c index aec071c..7b85a67 100644 --- a/unix/tclLoadDl.c +++ b/unix/tclLoadDl.c @@ -210,15 +210,14 @@ FindSymbol( * * UnloadFile -- * - * Unloads a dynamically loaded binary code file from memory. Code - * pointers in the formerly loaded file are no longer valid after calling - * this function. + * Unloads a dynamic shared object, after which all pointers to functions + * in the formerly-loaded object are no longer valid. * * Results: * None. * * Side effects: - * Code removed from memory. + * Memory for the loaded object is deallocated. * *---------------------------------------------------------------------- */ diff --git a/unix/tclUnixFCmd.c b/unix/tclUnixFCmd.c index b214627..3fdf95a 100644 --- a/unix/tclUnixFCmd.c +++ b/unix/tclUnixFCmd.c @@ -1922,17 +1922,14 @@ GetModeFromPermString( * * TclpObjNormalizePath -- * - * This function scans through a path specification and replaces it, in - * place, with a normalized version. A normalized version is one in which - * all symlinks in the path are replaced with their expanded form (except - * a symlink at the very end of the path). + * Replaces each component except that last one in a pathname that is a + * symbolic link with the fully resolved target of that link. * * Results: - * The new 'nextCheckpoint' value, giving as far as we could understand - * in the path. + * Stores the resulting path in pathPtr and returns the offset of the last + * byte processed to obtain the resulting path. * * Side effects: - * The pathPtr string, is modified. * *--------------------------------------------------------------------------- */ @@ -1940,8 +1937,14 @@ GetModeFromPermString( int TclpObjNormalizePath( Tcl_Interp *interp, - Tcl_Obj *pathPtr, - int nextCheckpoint) + Tcl_Obj *pathPtr, /* An unshared object containing the path to + * normalize. */ + int nextCheckpoint) /* offset to start at in pathPtr. Must either + * be 0 or the offset of a directory separator + * at the end of a path part that is already + * normalized. I.e. this is not the index of + * the byte just after the separator. */ + { const char *currentPathEndPosition; char cur; @@ -1953,23 +1956,17 @@ TclpObjNormalizePath( char normPath[MAXPATHLEN]; #endif - /* - * We add '1' here because if nextCheckpoint is zero we know that '/' - * exists, and if it isn't zero, it must point at a directory separator - * which we also know exists. - */ - currentPathEndPosition = path + nextCheckpoint; if (*currentPathEndPosition == '/') { currentPathEndPosition++; } #ifndef NO_REALPATH - /* - * For speed, try to get the entire path in one go. - */ - if (nextCheckpoint == 0 && haveRealpath) { + /* + * Try to get the entire path in one go + */ + char *lastDir = strrchr(currentPathEndPosition, '/'); if (lastDir != NULL) { @@ -1978,8 +1975,13 @@ TclpObjNormalizePath( if (Realpath(nativePath, normPath) != NULL) { if (*nativePath != '/' && *normPath == '/') { /* - * realpath has transformed a relative path into an - * absolute path, we do not know how to handle this. + * realpath transformed a relative path into an + * absolute path. Fall back to the long way. + */ + + /* + * To do: This logic seems to be out of date. This whole + * routine should be reviewed and cleaed up. */ } else { nextCheckpoint = lastDir - path; @@ -2018,13 +2020,13 @@ TclpObjNormalizePath( } /* - * Update the acceptable point. + * Assign the end of the current component to nextCheckpoint */ nextCheckpoint = currentPathEndPosition - path; } else if (cur == 0) { /* - * Reached end of string. + * The end of the string. */ break; @@ -2033,22 +2035,19 @@ TclpObjNormalizePath( } /* - * We should really now convert this to a canonical path. We do that with - * 'realpath' if we have it available. Otherwise we could step through - * every single path component, checking whether it is a symlink, but that - * would be a lot of work, and most modern OSes have 'realpath'. + * Call 'realpath' to obtain a canonical path. */ #ifndef NO_REALPATH if (haveRealpath) { - /* - * If we only had '/foo' or '/' then we never increment nextCheckpoint - * and we don't need or want to go through 'Realpath'. Also, on some - * platforms, passing an empty string to 'Realpath' will give us the - * normalized pwd, which is not what we want at all! - */ - if (nextCheckpoint == 0) { + /* + * The path contains at most one component, e.g. '/foo' or '/', so + * so there is nothing to resolve. Also, on some platforms + * 'Realpath' transforms an empty string into the normalized pwd, + * which is the wrong answer. + */ + return 0; } @@ -2061,18 +2060,19 @@ TclpObjNormalizePath( if ((newNormLen == Tcl_DStringLength(&ds)) && (strcmp(normPath, nativePath) == 0)) { /* - * String is unchanged. + * The original path is unchanged. */ Tcl_DStringFree(&ds); /* - * Enable this to have the native FS claim normalization of - * the whole path for existing files. That would permit the - * caller to declare normalization complete without calls to - * additional filesystems. Saving lots of calls is probably - * worth the extra access() time here. When no other FS's are - * registered though, things are less clear. + * Uncommenting this would mean that this native filesystem + * routine claims the path is normalized if the file exists, + * which would permit the caller to avoid iterating through + * other filesystems filesystems. Saving lots of calls is + * probably worth the extra access() time, but in the common + * case that no other filesystems are registered this is an + * unnecessary expense. * if (0 == access(normPath, F_OK)) { return pathLen; @@ -2083,8 +2083,7 @@ TclpObjNormalizePath( } /* - * Free up the native path and put in its place the converted, - * normalized path. + * Free the original path and replace it with the normalized path. */ Tcl_DStringFree(&ds); @@ -2092,7 +2091,7 @@ TclpObjNormalizePath( if (path[nextCheckpoint] != '\0') { /* - * Not at end, append remaining path. + * Append the remaining path components. */ int normLen = Tcl_DStringLength(&ds); @@ -2101,7 +2100,8 @@ TclpObjNormalizePath( pathLen - nextCheckpoint); /* - * We recognise up to and including the directory separator. + * characters up to and including the directory separator have + * been processed */ nextCheckpoint = normLen + 1; @@ -2113,10 +2113,6 @@ TclpObjNormalizePath( nextCheckpoint = Tcl_DStringLength(&ds); } - /* - * Overwrite with the normalized path. - */ - Tcl_SetStringObj(pathPtr, Tcl_DStringValue(&ds), Tcl_DStringLength(&ds)); } @@ -2389,24 +2385,26 @@ static const int attributeArray[] = { * * GetUnixFileAttributes * - * Gets the readonly attribute of a file. + * Gets an attribute of a file. * * Results: - * Standard TCL result. Returns a new Tcl_Obj in attributePtrPtr if there - * is no error. The object will have ref count 0. + * A standard Tcl result. * * Side effects: - * A new object is allocated. + * If there is no error assigns to *attributePtrPtr the address of a new + * Tcl_Obj having a refCount of zero and containing the value of the + * specified attribute. + * * *---------------------------------------------------------------------- */ static int GetUnixFileAttributes( - Tcl_Interp *interp, /* The interp we are using for errors. */ + Tcl_Interp *interp, /* The interp to report errors to. */ int objIndex, /* The index of the attribute. */ - Tcl_Obj *fileName, /* The name of the file (UTF-8). */ - Tcl_Obj **attributePtrPtr) /* A pointer to return the object with. */ + Tcl_Obj *fileName, /* The pathname of the file (UTF-8). */ + Tcl_Obj **attributePtrPtr) /* Where to store the result. */ { int fileAttributes; WCHAR *winPath = winPathFromObj(fileName); diff --git a/win/tclWinFile.c b/win/tclWinFile.c index 880adc0..7699f7d 100644 --- a/win/tclWinFile.c +++ b/win/tclWinFile.c @@ -2542,8 +2542,9 @@ TclpFilesystemPathType( int TclpObjNormalizePath( Tcl_Interp *interp, - Tcl_Obj *pathPtr, - int nextCheckpoint) + Tcl_Obj *pathPtr, /* An unshared object containing the path to + * normalize */ + int nextCheckpoint) /* offset to start at in pathPtr */ { char *lastValidPathEnd = NULL; Tcl_DString dsNorm; /* This will hold the normalized string. */ @@ -3032,7 +3033,7 @@ TclpNativeToNormalized( * The nativePath representation. * * Side effects: - * Memory will be allocated. The path may need to be normalized. + * Memory will be allocated. The path might be normalized. * *--------------------------------------------------------------------------- */ -- cgit v0.12 From 41cd7b2754b0d81fb8fc35f0a3abaace7249471c Mon Sep 17 00:00:00 2001 From: sebres Date: Wed, 6 Nov 2019 23:03:43 +0000 Subject: cmdMZ.test: solved timing issues (too slow machines, debug builds, etc) --- tests/cmdMZ.test | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/tests/cmdMZ.test b/tests/cmdMZ.test index 5f94777..f72d39f 100644 --- a/tests/cmdMZ.test +++ b/tests/cmdMZ.test @@ -29,8 +29,6 @@ namespace eval ::tcl::test::cmdMZ { namespace import ::tcl::unsupported::timerate } - testConstraint knownMsvcBug [expr {![info exists ::env(TRAVIS_OS_NAME)] || ![string match windows $::env(TRAVIS_OS_NAME)]}] - # Tcl_PwdObjCmd test cmdMZ-1.1 {Tcl_PwdObjCmd} { @@ -333,8 +331,12 @@ test cmdMZ-4.13 {Tcl_SplitObjCmd: basic split commands} { proc _nrt_sleep {msec} { set usec [expr {$msec * 1000}] set stime [clock microseconds] - while {abs([clock microseconds] - $stime) < $usec} {after 0} + while {abs([clock microseconds] - $stime) < $usec} { + # don't use after 0 unless it's NRT-capable, so yes - busy-wait (but it's more precise): + # after 0 + } } +_nrt_sleep 0; # warm up (clock, compile, etc) test cmdMZ-5.1 {Tcl_TimeObjCmd: basic format of command} { list [catch {time} msg] $msg @@ -351,8 +353,8 @@ test cmdMZ-5.4 {Tcl_TimeObjCmd: nothing happens with negative iteration counts} test cmdMZ-5.5 {Tcl_TimeObjCmd: result format} { regexp {^\d+ microseconds per iteration} [time {format 1}] } 1 -test cmdMZ-5.6 {Tcl_TimeObjCmd: slower commands take longer} knownMsvcBug { - expr {[lindex [time {_nrt_sleep 1}] 0] < [lindex [time {_nrt_sleep 20}] 0]} +test cmdMZ-5.6 {Tcl_TimeObjCmd: slower commands take longer} { + expr {[lindex [time {_nrt_sleep 0.01}] 0] < [lindex [time {_nrt_sleep 10.0}] 0]} } 1 test cmdMZ-5.7 {Tcl_TimeObjCmd: errors generate right trace} { list [catch {time {error foo}} msg] $msg $::errorInfo @@ -404,19 +406,20 @@ test cmdMZ-6.5a {Tcl_TimeRateObjCmd: result format and one iteration} { test cmdMZ-6.5b {Tcl_TimeRateObjCmd: result format without iterations} { regexp {^0 \ws/# 0 # 0 #/sec 0 net-ms$} [timerate {} 0 0] } 1 -test cmdMZ-6.6 {Tcl_TimeRateObjCmd: slower commands take longer, but it remains almost the same time of measument} knownMsvcBug { - set m1 [timerate {_nrt_sleep 0} 20] - set m2 [timerate {_nrt_sleep 0.2} 20] +test cmdMZ-6.6 {Tcl_TimeRateObjCmd: slower commands take longer, but it remains almost the same time of measument} { + lassign [timerate {_nrt_sleep 0} 50] ovh + set m1 [timerate -overhead $ovh {_nrt_sleep 0.01} 50] + set m2 [timerate -overhead $ovh {_nrt_sleep 1.00} 50] list \ [expr {[lindex $m1 0] < [lindex $m2 0]}] \ [expr {[lindex $m1 0] < 100}] \ [expr {[lindex $m2 0] > 100}] \ - [expr {[lindex $m1 2] > 1000}] \ - [expr {[lindex $m2 2] < 1000}] \ - [expr {[lindex $m1 4] > 50000}] \ - [expr {[lindex $m2 4] < 50000}] \ - [expr {[lindex $m1 6] > 10 && [lindex $m1 6] < 100}] \ - [expr {[lindex $m2 6] > 10 && [lindex $m2 6] < 100}] + [expr {[lindex $m1 2] > 500}] \ + [expr {[lindex $m2 2] < 500}] \ + [expr {[lindex $m1 4] > 10000}] \ + [expr {[lindex $m2 4] < 10000}] \ + [expr {[lindex $m1 6] > 5 && [lindex $m1 6] < 100}] \ + [expr {[lindex $m2 6] > 5 && [lindex $m2 6] < 100}] } [lrepeat 9 1] test cmdMZ-6.7 {Tcl_TimeRateObjCmd: errors generate right trace} { list [catch {timerate {error foo} 1} msg] $msg $::errorInfo -- cgit v0.12 From dd8793f10dce07f7111054c83df565e501e5f4f4 Mon Sep 17 00:00:00 2001 From: "jan.nijtmans" Date: Thu, 7 Nov 2019 13:56:25 +0000 Subject: Deprecate mp_div_3(): Will be private function in future libtommath, not used in Tcl. Deprecate mp_sqr() stub entry: Will be converted to macro calling mp_mul(). --- generic/tclStubInit.c | 19 +++++++++++-------- generic/tclTomMath.decls | 4 ++-- generic/tclTomMathDecls.h | 14 ++++++++++---- libtommath/bn_mp_mul.c | 4 +++- 4 files changed, 26 insertions(+), 15 deletions(-) diff --git a/generic/tclStubInit.c b/generic/tclStubInit.c index 087adfc..54cd83c 100644 --- a/generic/tclStubInit.c +++ b/generic/tclStubInit.c @@ -121,14 +121,6 @@ mp_err TclBN_mp_div_d(const mp_int *a, unsigned int b, mp_int *c, unsigned int * } return result; } -mp_err TclBN_mp_div_3(const mp_int *a, mp_int *c, unsigned int *d) { - mp_digit d2; - mp_err result = TclBN_s_mp_div_3(a, c, &d2); - if (d) { - *d = d2; - } - return result; -} mp_err TclBN_mp_init_set(mp_int *a, unsigned int b) { return TclBN_s_mp_init_set(a, b); } @@ -146,6 +138,8 @@ void TclBN_mp_set(mp_int *a, unsigned int b) { # define TclBN_mp_to_unsigned_bin 0 # define TclBN_mp_to_unsigned_bin_n 0 # define TclBN_mp_toradix_n 0 +# define TclBN_mp_sqr 0 +# define TclBN_mp_div_3 0 # define TclSetStartupScriptPath 0 # define TclGetStartupScriptPath 0 # define TclSetStartupScriptFileName 0 @@ -178,6 +172,15 @@ void TclBN_mp_set(mp_int *a, unsigned int b) { # define Tcl_BackgroundError 0 #else +mp_err TclBN_mp_div_3(const mp_int *a, mp_int *c, unsigned int *d) { + mp_digit d2; + mp_err result = TclBN_s_mp_div_3(a, c, &d2); + if (d) { + *d = d2; + } + return result; +} + int TclBN_mp_expt_d_ex(const mp_int *a, unsigned int b, mp_int *c, int fast) { return mp_expt_u32(a, b, c); diff --git a/generic/tclTomMath.decls b/generic/tclTomMath.decls index f95371e..723bb0a 100644 --- a/generic/tclTomMath.decls +++ b/generic/tclTomMath.decls @@ -74,7 +74,7 @@ declare 15 { declare 16 { mp_err MP_WUR TclBN_mp_div_2d(const mp_int *a, int b, mp_int *q, mp_int *r) } -declare 17 { +declare 17 {deprecated {is private function in libtommath}} { mp_err MP_WUR TclBN_mp_div_3(const mp_int *a, mp_int *q, unsigned int *r) } declare 18 { @@ -143,7 +143,7 @@ declare 38 { declare 39 { void TclBN_mp_set(mp_int *a, unsigned int b) } -declare 40 { +declare 40 {nostub {is private function in libtommath}} { mp_err MP_WUR TclBN_mp_sqr(const mp_int *a, mp_int *b) } declare 41 { diff --git a/generic/tclTomMathDecls.h b/generic/tclTomMathDecls.h index c3032b1..cead9ad 100644 --- a/generic/tclTomMathDecls.h +++ b/generic/tclTomMathDecls.h @@ -106,7 +106,6 @@ MODULE_SCOPE mp_err TclBN_s_mp_expt_u32(const mp_int *a, unsigned int b, mp_int #define mp_set_ul TclBN_mp_set_ul #define mp_set_ull TclBN_mp_set_ull #define mp_shrink TclBN_mp_shrink -#define mp_sqr TclBN_mp_sqr #define mp_sqrt TclBN_mp_sqrt #define mp_sub TclBN_mp_sub #define mp_signed_rsh TclBN_mp_signed_rsh @@ -205,7 +204,8 @@ EXTERN mp_err TclBN_mp_div_2(const mp_int *a, mp_int *q) MP_WUR; EXTERN mp_err TclBN_mp_div_2d(const mp_int *a, int b, mp_int *q, mp_int *r) MP_WUR; /* 17 */ -EXTERN mp_err TclBN_mp_div_3(const mp_int *a, mp_int *q, +TCL_DEPRECATED("is private function in libtommath") +mp_err MP_WUR TclBN_mp_div_3(const mp_int *a, mp_int *q, unsigned int *r) MP_WUR; /* 18 */ EXTERN void TclBN_mp_exch(mp_int *a, mp_int *b); @@ -399,7 +399,7 @@ typedef struct TclTomMathStubs { mp_err (*tclBN_mp_div_d) (const mp_int *a, unsigned int b, mp_int *q, unsigned int *r) MP_WUR; /* 14 */ mp_err (*tclBN_mp_div_2) (const mp_int *a, mp_int *q) MP_WUR; /* 15 */ mp_err (*tclBN_mp_div_2d) (const mp_int *a, int b, mp_int *q, mp_int *r) MP_WUR; /* 16 */ - mp_err (*tclBN_mp_div_3) (const mp_int *a, mp_int *q, unsigned int *r) MP_WUR; /* 17 */ + TCL_DEPRECATED_API("is private function in libtommath") mp_err (*tclBN_mp_div_3) (const mp_int *a, mp_int *q, unsigned int *r) MP_WUR; /* 17 */ void (*tclBN_mp_exch) (mp_int *a, mp_int *b); /* 18 */ mp_err (*tclBN_mp_expt_u32) (const mp_int *a, unsigned int b, mp_int *c) MP_WUR; /* 19 */ mp_err (*tclBN_mp_grow) (mp_int *a, int size) MP_WUR; /* 20 */ @@ -422,7 +422,7 @@ typedef struct TclTomMathStubs { void (*tclBN_mp_rshd) (mp_int *a, int shift); /* 37 */ mp_err (*tclBN_mp_shrink) (mp_int *a) MP_WUR; /* 38 */ void (*tclBN_mp_set) (mp_int *a, unsigned int b); /* 39 */ - mp_err (*tclBN_mp_sqr) (const mp_int *a, mp_int *b) MP_WUR; /* 40 */ + TCL_DEPRECATED_API("is private function in libtommath") mp_err (*tclBN_mp_sqr) (const mp_int *a, mp_int *b) MP_WUR; /* 40 */ mp_err (*tclBN_mp_sqrt) (const mp_int *a, mp_int *b) MP_WUR; /* 41 */ mp_err (*tclBN_mp_sub) (const mp_int *a, const mp_int *b, mp_int *c) MP_WUR; /* 42 */ mp_err (*tclBN_mp_sub_d) (const mp_int *a, unsigned int b, mp_int *c) MP_WUR; /* 43 */ @@ -666,4 +666,10 @@ extern const TclTomMathStubs *tclTomMathStubsPtr; #undef TCL_STORAGE_CLASS #define TCL_STORAGE_CLASS DLLIMPORT +#if defined(USE_TCL_STUBS) +# define mp_sqr(a,b) mp_mul(a,a,b) +#else +# define mp_sqr TclBN_mp_sqr +#endif + #endif /* _TCLINTDECLS */ diff --git a/libtommath/bn_mp_mul.c b/libtommath/bn_mp_mul.c index c76b97d..c4890c5 100644 --- a/libtommath/bn_mp_mul.c +++ b/libtommath/bn_mp_mul.c @@ -12,7 +12,9 @@ mp_err mp_mul(const mp_int *a, const mp_int *b, mp_int *c) digs = a->used + b->used + 1; mp_sign neg = (a->sign == b->sign) ? MP_ZPOS : MP_NEG; - if (MP_HAS(S_MP_BALANCE_MUL) && + if (a == b) { + return mp_sqr(a,c); + } else if (MP_HAS(S_MP_BALANCE_MUL) && /* Check sizes. The smaller one needs to be larger than the Karatsuba cut-off. * The bigger one needs to be at least about one MP_KARATSUBA_MUL_CUTOFF bigger * to make some sense, but it depends on architecture, OS, position of the -- cgit v0.12