diff options
Diffstat (limited to 'include/iprt/strcache.h')
| -rw-r--r-- | include/iprt/strcache.h | 73 |
1 files changed, 70 insertions, 3 deletions
diff --git a/include/iprt/strcache.h b/include/iprt/strcache.h index d3883483..65cfd484 100644 --- a/include/iprt/strcache.h +++ b/include/iprt/strcache.h @@ -4,7 +4,7 @@ */ /* - * Copyright (C) 2009 Oracle Corporation + * Copyright (C) 2009-2010 Oracle Corporation * * This file is part of VirtualBox Open Source Edition (OSE), as * available from http://www.virtualbox.org. This file is free software; @@ -87,6 +87,35 @@ RTDECL(const char *) RTStrCacheEnter(RTSTRCACHE hStrCache, const char *psz); /** + * Enters a string into the cache in lower cased form. + * + * @returns Pointer to a read-only lower cased copy of the string. + * + * @param hStrCache Handle to the string cache. + * @param pchString Pointer to a string. This does not need to be + * zero terminated, but must not contain any zero + * characters. + * @param cchString The number of characters (bytes) to enter. + * + * @remarks It is implementation dependent whether the returned string pointer + * differs when entering the same string twice. + */ +RTDECL(const char *) RTStrCacheEnterLowerN(RTSTRCACHE hStrCache, const char *pchString, size_t cchString); + +/** + * Enters a string into the cache in lower cased form. + * + * @returns Pointer to a read-only lower cased copy of the string. + * + * @param hStrCache Handle to the string cache. + * @param psz Pointer to a zero terminated string. + * + * @remarks See RTStrCacheEnterN. + */ +RTDECL(const char *) RTStrCacheEnterLower(RTSTRCACHE hStrCache, const char *psz); + + +/** * Retains a reference to a string. * * @returns The new reference count. UINT32_MAX is returned if the string @@ -100,8 +129,7 @@ RTDECL(uint32_t) RTStrCacheRetain(const char *psz); * @returns The new reference count. * UINT32_MAX is returned if the string pointer is invalid. * - * @param hStrCache Handle to the string cache. Passing NIL is ok, - * but this may come a performance hit. + * @param hStrCache Handle to the string cache. NIL is NOT allowed. * @param psz Pointer to a cached string. */ RTDECL(uint32_t) RTStrCacheRelease(RTSTRCACHE hStrCache, const char *psz); @@ -115,6 +143,45 @@ RTDECL(uint32_t) RTStrCacheRelease(RTSTRCACHE hStrCache, const char *psz); */ RTDECL(size_t) RTStrCacheLength(const char *psz); + +/** + * Gets cache statistics. + * + * All parameters, except @a hStrCache, are optional and can be NULL. + * + * @returns Number of strings, UINT32_MAX on failure (or not supported). + * @param hStrCache Handle to the string cache. + * @param pcbStrings The number of string bytes (including + * terminators) . + * @param pcbChunks Amount of memory we've allocated for the + * internal allocator. + * @param pcbBigEntries Amount of memory we've allocated off the heap + * for really long strings that doesn't fit in the + * internal allocator. + * @param pcHashCollisions Number of hash table insert collisions. + * @param pcHashCollisions2 Number of hash table secondary insert + * collisions. + * @param pcHashInserts Number of hash table inserts. + * @param pcRehashes The number of rehashes. + * + * @remarks This is not a stable interface as it needs to reflect the cache + * implementation. + */ +RTDECL(uint32_t) RTStrCacheGetStats(RTSTRCACHE hStrCache, size_t *pcbStrings, size_t *pcbChunks, size_t *pcbBigEntries, + uint32_t *pcHashCollisions, uint32_t *pcHashCollisions2, uint32_t *pcHashInserts, + uint32_t *pcRehashes); + +/** + * Indicates whether this a real string cache or a cheap place holder. + * + * A real string cache will return the same address when a string is added + * multiple times. + * + * @returns true / false. + */ +RTDECL(bool) RTStrCacheIsRealImpl(void); + + RT_C_DECLS_END #endif |