20593760b116c90f3e439552763eef632a3bbb17vboxsync * IPRT - String Cache, stub implementation.
c7814cf6e1240a519cbec0441e033d0e2470ed00vboxsync * Copyright (C) 2009-2010 Oracle Corporation
20593760b116c90f3e439552763eef632a3bbb17vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
20593760b116c90f3e439552763eef632a3bbb17vboxsync * available from http://www.virtualbox.org. This file is free software;
20593760b116c90f3e439552763eef632a3bbb17vboxsync * you can redistribute it and/or modify it under the terms of the GNU
20593760b116c90f3e439552763eef632a3bbb17vboxsync * General Public License (GPL) as published by the Free Software
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
20593760b116c90f3e439552763eef632a3bbb17vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
20593760b116c90f3e439552763eef632a3bbb17vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * The contents of this file may alternatively be used under the terms
20593760b116c90f3e439552763eef632a3bbb17vboxsync * of the Common Development and Distribution License Version 1.0
20593760b116c90f3e439552763eef632a3bbb17vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20593760b116c90f3e439552763eef632a3bbb17vboxsync * VirtualBox OSE distribution, in which case the provisions of the
20593760b116c90f3e439552763eef632a3bbb17vboxsync * CDDL are applicable instead of those of the GPL.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * You may elect to license modified versions of this file under the
20593760b116c90f3e439552763eef632a3bbb17vboxsync * terms and conditions of either the GPL or the CDDL or both.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Create a new string cache.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns IPRT status code
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param phStrCache Where to return the string cache handle.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param pszName The name of the cache (for debug purposes).
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(int) RTStrCacheCreate(PRTSTRCACHE phStrCache, const char *pszName);
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Destroys a string cache.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * This will cause all strings in the cache to be released and thus become
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns IPRT status.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param hStrCache Handle to the string cache. The nil and default
20593760b116c90f3e439552763eef632a3bbb17vboxsync * handles are ignored quietly (VINF_SUCCESS).
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(int) RTStrCacheDestroy(RTSTRCACHE hStrCache);
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Enters a string into the cache.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns Pointer to a read-only copy of the string.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param hStrCache Handle to the string cache.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param pchString Pointer to a string. This does not need to be
20593760b116c90f3e439552763eef632a3bbb17vboxsync * zero terminated, but must not contain any zero
20593760b116c90f3e439552763eef632a3bbb17vboxsync * characters.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param cchString The number of characters (bytes) to enter.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @remarks It is implementation dependent whether the returned string pointer
20593760b116c90f3e439552763eef632a3bbb17vboxsync * differs when entering the same string twice.
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(const char *) RTStrCacheEnterN(RTSTRCACHE hStrCache, const char *pchString, size_t cchString);
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Enters a string into the cache.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns Pointer to a read-only copy of the string.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param hStrCache Handle to the string cache.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param psz Pointer to a zero terminated string.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @remarks See RTStrCacheEnterN.
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(const char *) RTStrCacheEnter(RTSTRCACHE hStrCache, const char *psz);
e9525bea57dc13d82fd3392913aebb33d2cb79e3vboxsync * Enters a string into the cache in lower cased form.
e9525bea57dc13d82fd3392913aebb33d2cb79e3vboxsync * @returns Pointer to a read-only lower cased copy of the string.
e9525bea57dc13d82fd3392913aebb33d2cb79e3vboxsync * @param hStrCache Handle to the string cache.
e9525bea57dc13d82fd3392913aebb33d2cb79e3vboxsync * @param pchString Pointer to a string. This does not need to be
e9525bea57dc13d82fd3392913aebb33d2cb79e3vboxsync * zero terminated, but must not contain any zero
e9525bea57dc13d82fd3392913aebb33d2cb79e3vboxsync * characters.
e9525bea57dc13d82fd3392913aebb33d2cb79e3vboxsync * @param cchString The number of characters (bytes) to enter.
e9525bea57dc13d82fd3392913aebb33d2cb79e3vboxsync * @remarks It is implementation dependent whether the returned string pointer
e9525bea57dc13d82fd3392913aebb33d2cb79e3vboxsync * differs when entering the same string twice.
e9525bea57dc13d82fd3392913aebb33d2cb79e3vboxsyncRTDECL(const char *) RTStrCacheEnterLowerN(RTSTRCACHE hStrCache, const char *pchString, size_t cchString);
e9525bea57dc13d82fd3392913aebb33d2cb79e3vboxsync * Enters a string into the cache in lower cased form.
e9525bea57dc13d82fd3392913aebb33d2cb79e3vboxsync * @returns Pointer to a read-only lower cased copy of the string.
e9525bea57dc13d82fd3392913aebb33d2cb79e3vboxsync * @param hStrCache Handle to the string cache.
e9525bea57dc13d82fd3392913aebb33d2cb79e3vboxsync * @param psz Pointer to a zero terminated string.
e9525bea57dc13d82fd3392913aebb33d2cb79e3vboxsync * @remarks See RTStrCacheEnterN.
e9525bea57dc13d82fd3392913aebb33d2cb79e3vboxsyncRTDECL(const char *) RTStrCacheEnterLower(RTSTRCACHE hStrCache, const char *psz);
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Retains a reference to a string.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns The new reference count. UINT32_MAX is returned if the string
20593760b116c90f3e439552763eef632a3bbb17vboxsync * pointer is invalid.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Releases a reference to a string.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns The new reference count.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * UINT32_MAX is returned if the string pointer is invalid.
68b3acaa752c9d4d19af6f51183c2131543e7db9vboxsync * @param hStrCache Handle to the string cache. NIL is NOT allowed.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param psz Pointer to a cached string.
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(uint32_t) RTStrCacheRelease(RTSTRCACHE hStrCache, const char *psz);
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Gets the string length of a cache entry.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns The string length. 0 if the string is invalid (asserted).
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param psz Pointer to a cached string.
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * Gets cache statistics.
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * All parameters, except @a hStrCache, are optional and can be NULL.
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * @returns Number of strings, UINT32_MAX on failure (or not supported).
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * @param hStrCache Handle to the string cache.
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * @param pcbStrings The number of string bytes (including
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * terminators) .
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * @param pcbChunks Amount of memory we've allocated for the
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * internal allocator.
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * @param pcbBigEntries Amount of memory we've allocated off the heap
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * for really long strings that doesn't fit in the
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * internal allocator.
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * @param pcHashCollisions Number of hash table insert collisions.
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * @param pcHashCollisions2 Number of hash table secondary insert
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * collisions.
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * @param pcHashInserts Number of hash table inserts.
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * @param pcRehashes The number of rehashes.
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * @remarks This is not a stable interface as it needs to reflect the cache
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync * implementation.
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsyncRTDECL(uint32_t) RTStrCacheGetStats(RTSTRCACHE hStrCache, size_t *pcbStrings, size_t *pcbChunks, size_t *pcbBigEntries,
e00b7e275dee70ffbd9e00a3e3e3e8513287e2b2vboxsync uint32_t *pcHashCollisions, uint32_t *pcHashCollisions2, uint32_t *pcHashInserts,
a18faae7b59910c9f2da2886ac10d7f31e29cd83vboxsync * Indicates whether this a real string cache or a cheap place holder.
a18faae7b59910c9f2da2886ac10d7f31e29cd83vboxsync * A real string cache will return the same address when a string is added
a18faae7b59910c9f2da2886ac10d7f31e29cd83vboxsync * multiple times.
a18faae7b59910c9f2da2886ac10d7f31e29cd83vboxsync * @returns true / false.