From b2190d273f42dc51a6455279afdf00695c45c12b Mon Sep 17 00:00:00 2001 From: sebres Date: Wed, 11 Jan 2017 16:36:28 +0000 Subject: code review and inline documentation --- generic/tclClock.c | 27 +++++ generic/tclClockFmt.c | 323 +++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 323 insertions(+), 27 deletions(-) diff --git a/generic/tclClock.c b/generic/tclClock.c index efa9120..c63f425 100644 --- a/generic/tclClock.c +++ b/generic/tclClock.c @@ -412,7 +412,19 @@ NormTimezoneObj( /* *---------------------------------------------------------------------- + * + * ClockGetSystemLocale -- + * + * Returns system locale. + * + * Executes ::tcl::clock::GetSystemLocale in given interpreter. + * + * Results: + * Returns system locale tcl object. + * + *---------------------------------------------------------------------- */ + static inline Tcl_Obj * ClockGetSystemLocale( ClockClientData *dataPtr, /* Opaque pointer to literal pool, etc. */ @@ -426,7 +438,19 @@ ClockGetSystemLocale( } /* *---------------------------------------------------------------------- + * + * ClockGetCurrentLocale -- + * + * Returns current locale. + * + * Executes ::tcl::clock::mclocale in given interpreter. + * + * Results: + * Returns current locale tcl object. + * + *---------------------------------------------------------------------- */ + static inline Tcl_Obj * ClockGetCurrentLocale( ClockClientData *dataPtr, /* Client data containing literal pool */ @@ -978,6 +1002,9 @@ ClockGetTZData( * * Returns system (current) timezone. * + * If system zone not yet cached, it executes ::tcl::clock::GetSystemTimeZone + * in given interpreter and caches its result. + * * Results: * Returns normalized timezone object. * diff --git a/generic/tclClockFmt.c b/generic/tclClockFmt.c index ff16714..d875bd4 100644 --- a/generic/tclClockFmt.c +++ b/generic/tclClockFmt.c @@ -41,6 +41,24 @@ CLOCK_LOCALE_LITERAL_ARRAY(MsgCtLitIdxs, "_IDX_"); * Clock scan and format facilities. */ +/* + *---------------------------------------------------------------------- + * + * _str2int -- , _str2wideInt -- + * + * Fast inline-convertion of string to signed int or wide int by given + * start/end. + * + * The given string should contain numbers chars only (because already + * pre-validated within parsing routines) + * + * Results: + * Returns a standard Tcl result. + * TCL_OK - by successful conversion, TCL_ERROR by (wide) int overflow + * + *---------------------------------------------------------------------- + */ + static inline int _str2int( int *out, @@ -101,6 +119,22 @@ _str2wideInt( return TCL_OK; } +/* + *---------------------------------------------------------------------- + * + * _itoaw -- , _witoaw -- + * + * Fast inline-convertion of signed int or wide int to string, using + * given padding with specified padchar and width (or without padding). + * + * This is a very fast replacement for sprintf("%02d"). + * + * Results: + * Returns position in buffer after end of conversion result. + * + *---------------------------------------------------------------------- + */ + static inline char * _itoaw( char *buf, @@ -257,7 +291,15 @@ _witoaw( } /* - *---------------------------------------------------------------------- + * Global GC as LIFO for released scan/format object storages. + * + * Used to holds last released CLOCK_FMT_SCN_STORAGE_GC_SIZE formats + * (after last reference from Tcl-object will be removed). This is helpful + * to avoid continuous (re)creation and compiling by some dynamically resp. + * variable format objects, that could be often reused. + * + * As long as format storage is used resp. belongs to GC, it takes place in + * FmtScnHashTable also. */ #if CLOCK_FMT_SCN_STORAGE_GC_SIZE > 0 @@ -268,6 +310,24 @@ static struct { unsigned int count; } ClockFmtScnStorage_GC = {NULL, NULL, 0}; +/* + *---------------------------------------------------------------------- + * + * ClockFmtScnStorageGC_In -- + * + * Adds an format storage object to GC. + * + * If current GC is full (size larger as CLOCK_FMT_SCN_STORAGE_GC_SIZE) + * this removes last unused storage at begin of GC stack (LIFO). + * + * Assumes caller holds the ClockFmtMutex. + * + * Results: + * None. + * + *---------------------------------------------------------------------- + */ + static inline void ClockFmtScnStorageGC_In(ClockFmtScnStorage *entry) { @@ -291,6 +351,22 @@ ClockFmtScnStorageGC_In(ClockFmtScnStorage *entry) ClockFmtScnStorageDelete(delEnt); } } + +/* + *---------------------------------------------------------------------- + * + * ClockFmtScnStorage_GC_Out -- + * + * Restores (for reusing) given format storage object from GC. + * + * Assumes caller holds the ClockFmtMutex. + * + * Results: + * None. + * + *---------------------------------------------------------------------- + */ + static inline void ClockFmtScnStorage_GC_Out(ClockFmtScnStorage *entry) { @@ -304,13 +380,19 @@ ClockFmtScnStorage_GC_Out(ClockFmtScnStorage *entry) #endif + /* - *---------------------------------------------------------------------- + * Global format storage hash table of type ClockFmtScnStorageHashKeyType + * (contains list of scan/format object storages, shared across all threads). + * + * Used for fast searching by format string. */ - static Tcl_HashTable FmtScnHashTable; static int initialized = 0; +/* + * Wrappers between pointers to hash entry and format storage object + */ static inline Tcl_HashEntry * HashEntry4FmtScn(ClockFmtScnStorage *fss) { return (Tcl_HashEntry*)(fss + 1); @@ -320,8 +402,18 @@ FmtScn4HashEntry(Tcl_HashEntry *hKeyPtr) { return (ClockFmtScnStorage*)(((char*)hKeyPtr) - sizeof(ClockFmtScnStorage)); }; -/* - * Format storage hash (list of formats shared across all threads). +/* + *---------------------------------------------------------------------- + * + * ClockFmtScnStorageAllocProc -- + * + * Allocate space for a hash entry containing format storage together + * with the string key. + * + * Results: + * The return value is a pointer to the created entry. + * + *---------------------------------------------------------------------- */ static Tcl_HashEntry * @@ -353,6 +445,19 @@ ClockFmtScnStorageAllocProc( return hPtr; } +/* + *---------------------------------------------------------------------- + * + * ClockFmtScnStorageFreeProc -- + * + * Free format storage object and space of given hash entry. + * + * Results: + * None. + * + *---------------------------------------------------------------------- + */ + static void ClockFmtScnStorageFreeProc( Tcl_HashEntry *hPtr) @@ -373,6 +478,19 @@ ClockFmtScnStorageFreeProc( ckfree(fss); } +/* + *---------------------------------------------------------------------- + * + * ClockFmtScnStorageDelete -- + * + * Delete format storage object. + * + * Results: + * None. + * + *---------------------------------------------------------------------- + */ + static void ClockFmtScnStorageDelete(ClockFmtScnStorage *fss) { Tcl_HashEntry *hPtr = HashEntry4FmtScn(fss); @@ -392,7 +510,7 @@ static Tcl_HashKeyType ClockFmtScnStorageHashKeyType; /* - * Type definition. + * Type definition of clock-format tcl object type. */ Tcl_ObjType ClockFmtObjType = { @@ -409,9 +527,6 @@ Tcl_ObjType ClockFmtObjType = { #define ObjLocFmtKey(objPtr) \ (*((Tcl_Obj **)&(objPtr)->internalRep.twoPtrValue.ptr2)) -/* - *---------------------------------------------------------------------- - */ static void ClockFmtObj_DupInternalRep(srcPtr, copyPtr) Tcl_Obj *srcPtr; @@ -442,9 +557,7 @@ ClockFmtObj_DupInternalRep(srcPtr, copyPtr) copyPtr->length = srcPtr->length; } } -/* - *---------------------------------------------------------------------- - */ + static void ClockFmtObj_FreeInternalRep(objPtr) Tcl_Obj *objPtr; @@ -472,9 +585,7 @@ ClockFmtObj_FreeInternalRep(objPtr) } objPtr->typePtr = NULL; }; -/* - *---------------------------------------------------------------------- - */ + static int ClockFmtObj_SetFromAny(interp, objPtr) Tcl_Interp *interp; @@ -494,9 +605,7 @@ ClockFmtObj_SetFromAny(interp, objPtr) return TCL_OK; }; -/* - *---------------------------------------------------------------------- - */ + static void ClockFmtObj_UpdateString(objPtr) Tcl_Obj *objPtr; @@ -518,7 +627,25 @@ ClockFmtObj_UpdateString(objPtr) /* *---------------------------------------------------------------------- + * + * ClockFrmObjGetLocFmtKey -- + * + * Retrieves format key object used to search localized format. + * + * This is normally stored in second pointer of internal representation. + * If format object is not localizable, it is equal the given format + * pointer and the first pointer of internal representation may be NULL. + * + * Results: + * Returns tcl object with key or format object if not localizable. + * + * Side effects: + * Converts given format object to ClockFmtObjType on demand for caching + * the key inside its internal representation. + * + *---------------------------------------------------------------------- */ + MODULE_SCOPE Tcl_Obj* ClockFrmObjGetLocFmtKey( Tcl_Interp *interp, @@ -545,6 +672,25 @@ ClockFrmObjGetLocFmtKey( /* *---------------------------------------------------------------------- + * + * FindOrCreateFmtScnStorage -- + * + * Retrieves format storage for given string format. + * + * This will find the given format in the global storage hash table + * or create a format storage object on demaind and save the + * reference in the first pointer of internal representation of given + * object. + * + * Results: + * Returns scan/format storage pointer to ClockFmtScnStorage. + * + * Side effects: + * Converts given format object to ClockFmtObjType on demand for caching + * the format storage reference inside its internal representation. + * Increments objRefCount of the ClockFmtScnStorage reference. + * + *---------------------------------------------------------------------- */ static ClockFmtScnStorage * @@ -609,16 +755,16 @@ FindOrCreateFmtScnStorage( * * Tcl_GetClockFrmScnFromObj -- * - * Returns a clock format/scan representation of (*objPtr), if possible. - * If something goes wrong, NULL is returned, and if interp is non-NULL, - * an error message is written there. + * Returns a clock format/scan representation of (*objPtr), if possible. + * If something goes wrong, NULL is returned, and if interp is non-NULL, + * an error message is written there. * * Results: - * Valid representation of type ClockFmtScnStorage. + * Valid representation of type ClockFmtScnStorage. * * Side effects: - * Caches the ClockFmtScnStorage reference as the internal rep of (*objPtr) - * and in global hash table, shared across all threads. + * Caches the ClockFmtScnStorage reference as the internal rep of (*objPtr) + * and in global hash table, shared across all threads. * *---------------------------------------------------------------------- */ @@ -644,7 +790,27 @@ Tcl_GetClockFrmScnFromObj( return fss; } - +/* + *---------------------------------------------------------------------- + * + * ClockLocalizeFormat -- + * + * Wrap the format object in options to the localized format, + * corresponding given locale. + * + * This searches localized format in locale catalog, and if not yet + * exists, it executes ::tcl::clock::LocalizeFormat in given interpreter + * and caches its result in the locale catalog. + * + * Results: + * Localized format object. + * + * Side effects: + * Caches the localized format inside locale catalog. + * + *---------------------------------------------------------------------- + */ + MODULE_SCOPE Tcl_Obj * ClockLocalizeFormat( ClockFmtScnCmdArgs *opts) @@ -713,6 +879,22 @@ clean: return (opts->formatObj = valObj); } +/* + *---------------------------------------------------------------------- + * + * FindTokenBegin -- + * + * Find begin of given scan token in string, corresponding token type. + * + * Results: + * Position of token inside string if found. Otherwise - end of string. + * + * Side effects: + * None. + * + *---------------------------------------------------------------------- + */ + static const char * FindTokenBegin( register const char *p, @@ -748,12 +930,22 @@ FindTokenBegin( return p; } -/* +/* + *---------------------------------------------------------------------- + * * DetermineGreedySearchLen -- * - * Determine min/max lengths as exact as possible (speed, greedy match) + * Determine min/max lengths as exact as possible (speed, greedy match). * + * Results: + * None. Lengths are stored in *minLenPtr, *maxLenPtr. + * + * Side effects: + * None. + * + *---------------------------------------------------------------------- */ + static void DetermineGreedySearchLen(ClockFmtScnCmdArgs *opts, DateInfo *info, ClockScanToken *tok, @@ -836,6 +1028,23 @@ DetermineGreedySearchLen(ClockFmtScnCmdArgs *opts, *maxLenPtr = maxLen; } +/* + *---------------------------------------------------------------------- + * + * ObjListSearch -- + * + * Find largest part of the input string from start regarding min and + * max lengths in the given list (utf-8, case sensitive). + * + * Results: + * TCL_OK - match found, TCL_RETURN - not matched, TCL_ERROR in error case. + * + * Side effects: + * Input points to end of the found token in string. + * + *---------------------------------------------------------------------- + */ + static inline int ObjListSearch(ClockFmtScnCmdArgs *opts, DateInfo *info, int *val, @@ -909,6 +1118,26 @@ LocaleListSearch(ClockFmtScnCmdArgs *opts, } #endif +/* + *---------------------------------------------------------------------- + * + * ClockMCGetListIdxTree -- + * + * Retrieves localized string indexed tree in the locale catalog for + * given literal index mcKey (and builds it on demand). + * + * Searches localized index in locale catalog, and if not yet exists, + * creates string indexed tree and stores it in the locale catalog. + * + * Results: + * Localized string index tree. + * + * Side effects: + * Caches the localized string index tree inside locale catalog. + * + *---------------------------------------------------------------------- + */ + static TclStrIdxTree * ClockMCGetListIdxTree( ClockFmtScnCmdArgs *opts, @@ -960,6 +1189,27 @@ done: return idxTree; } +/* + *---------------------------------------------------------------------- + * + * ClockMCGetMultiListIdxTree -- + * + * Retrieves localized string indexed tree in the locale catalog for + * multiple lists by literal indices mcKeys (and builds it on demand). + * + * Searches localized index in locale catalog for mcKey, and if not + * yet exists, creates string indexed tree and stores it in the + * locale catalog. + * + * Results: + * Localized string index tree. + * + * Side effects: + * Caches the localized string index tree inside locale catalog. + * + *---------------------------------------------------------------------- + */ + static TclStrIdxTree * ClockMCGetMultiListIdxTree( ClockFmtScnCmdArgs *opts, @@ -1016,6 +1266,25 @@ done: return idxTree; } +/* + *---------------------------------------------------------------------- + * + * ClockStrIdxTreeSearch -- + * + * Find largest part of the input string from start regarding lengths + * in the given localized string indexed tree (utf-8, case sensitive). + * + * Results: + * TCL_OK - match found and the index stored in *val, + * TCL_RETURN - not matched or ambigous, + * TCL_ERROR - in error case. + * + * Side effects: + * Input points to end of the found token in string. + * + *---------------------------------------------------------------------- + */ + static inline int ClockStrIdxTreeSearch(ClockFmtScnCmdArgs *opts, DateInfo *info, TclStrIdxTree *idxTree, int *val, -- cgit v0.12