include/iprt/strcache.h

   1 /* $Id$ */
   2 /** @file
   3  * IPRT - String Cache, stub implementation.
   4  */
   5
   6 /*
   7  * Copyright (C) 2009-2024 Oracle and/or its affiliates.
   8  *
   9  * This file is part of VirtualBox base platform packages, as
  10  * available from https://www.virtualbox.org.
  11  *
  12  * This program is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU General Public License
  14  * as published by the Free Software Foundation, in version 3 of the
  15  * License.
  16  *
  17  * This program is distributed in the hope that it will be useful, but
  18  * WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20  * General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program; if not, see <https://www.gnu.org/licenses>.
  24  *
  25  * The contents of this file may alternatively be used under the terms
  26  * of the Common Development and Distribution License Version 1.0
  27  * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
  28  * in the VirtualBox distribution, in which case the provisions of the
  29  * CDDL are applicable instead of those of the GPL.
  30  *
  31  * You may elect to license modified versions of this file under the
  32  * terms and conditions of either the GPL or the CDDL or both.
  33  *
  34  * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
  35  */
  36
  37 #ifndef IPRT_INCLUDED_strcache_h
  38 #define IPRT_INCLUDED_strcache_h
  39 #ifndef RT_WITHOUT_PRAGMA_ONCE
  40 # pragma once
  41 #endif
  42
  43 #include <iprt/types.h>
  44
  45 RT_C_DECLS_BEGIN
  46
  47
  48 /**
  49  * Create a new string cache.
  50  *
  51  * @returns IPRT status code
  52  *
  53  * @param   phStrCache          Where to return the string cache handle.
  54  * @param   pszName             The name of the cache (for debug purposes).
  55  */
  56 RTDECL(int) RTStrCacheCreate(PRTSTRCACHE phStrCache, const char *pszName);
  57
  58
  59 /**
  60  * Destroys a string cache.
  61  *
  62  * This will cause all strings in the cache to be released and thus become
  63  * invalid.
  64  *
  65  * @returns IPRT status.
  66  *
  67  * @param   hStrCache           Handle to the string cache. The nil and default
  68  *                              handles are ignored quietly (VINF_SUCCESS).
  69  */
  70 RTDECL(int) RTStrCacheDestroy(RTSTRCACHE hStrCache);
  71
  72
  73 /**
  74  * Enters a string into the cache.
  75  *
  76  * @returns Pointer to a read-only copy of the string.
  77  *
  78  * @param   hStrCache           Handle to the string cache.
  79  * @param   pchString           Pointer to a string. This does not need to be
  80  *                              zero terminated, but must not contain any zero
  81  *                              characters.
  82  * @param   cchString           The number of characters (bytes) to enter.
  83  *
  84  * @remarks It is implementation dependent whether the returned string pointer
  85  *          differs when entering the same string twice.
  86  */
  87 RTDECL(const char *) RTStrCacheEnterN(RTSTRCACHE hStrCache, const char *pchString, size_t cchString);
  88
  89 /**
  90  * Enters a string into the cache.
  91  *
  92  * @returns Pointer to a read-only copy of the string.
  93  *
  94  * @param   hStrCache           Handle to the string cache.
  95  * @param   psz                 Pointer to a zero terminated string.
  96  *
  97  * @remarks See RTStrCacheEnterN.
  98  */
  99 RTDECL(const char *) RTStrCacheEnter(RTSTRCACHE hStrCache, const char *psz);
 100
 101
 102 /**
 103  * Enters a string into the cache in lower cased form.
 104  *
 105  * @returns Pointer to a read-only lower cased copy of the string.
 106  *
 107  * @param   hStrCache           Handle to the string cache.
 108  * @param   pchString           Pointer to a string. This does not need to be
 109  *                              zero terminated, but must not contain any zero
 110  *                              characters.
 111  * @param   cchString           The number of characters (bytes) to enter.
 112  *
 113  * @remarks It is implementation dependent whether the returned string pointer
 114  *          differs when entering the same string twice.
 115  */
 116 RTDECL(const char *) RTStrCacheEnterLowerN(RTSTRCACHE hStrCache, const char *pchString, size_t cchString);
 117
 118 /**
 119  * Enters a string into the cache in lower cased form.
 120  *
 121  * @returns Pointer to a read-only lower cased copy of the string.
 122  *
 123  * @param   hStrCache           Handle to the string cache.
 124  * @param   psz                 Pointer to a zero terminated string.
 125  *
 126  * @remarks See RTStrCacheEnterN.
 127  */
 128 RTDECL(const char *) RTStrCacheEnterLower(RTSTRCACHE hStrCache, const char *psz);
 129
 130
 131 /**
 132  * Retains a reference to a string.
 133  *
 134  * @returns The new reference count. UINT32_MAX is returned if the string
 135  *          pointer is invalid.
 136  */
 137 RTDECL(uint32_t) RTStrCacheRetain(const char *psz);
 138
 139 /**
 140  * Releases a reference to a string.
 141  *
 142  * @returns The new reference count.
 143  *          UINT32_MAX is returned if the string pointer is invalid.
 144  *
 145  * @param   hStrCache           Handle to the string cache. NIL is NOT allowed.
 146  * @param   psz                 Pointer to a cached string.
 147  */
 148 RTDECL(uint32_t) RTStrCacheRelease(RTSTRCACHE hStrCache, const char *psz);
 149
 150 /**
 151  * Gets the string length of a cache entry.
 152  *
 153  * @returns The string length. 0 if the string is invalid (asserted).
 154  *
 155  * @param   psz             Pointer to a cached string.
 156  */
 157 RTDECL(size_t) RTStrCacheLength(const char *psz);
 158
 159
 160 /**
 161  * Gets cache statistics.
 162  *
 163  * All parameters, except @a hStrCache, are optional and can be NULL.
 164  *
 165  * @returns Number of strings, UINT32_MAX on failure (or not supported).
 166  * @param   hStrCache           Handle to the string cache.
 167  * @param   pcbStrings          The number of string bytes (including
 168  *                              terminators) .
 169  * @param   pcbChunks           Amount of memory we've allocated for the
 170  *                              internal allocator.
 171  * @param   pcbBigEntries       Amount of memory we've allocated off the heap
 172  *                              for really long strings that doesn't fit in the
 173  *                              internal allocator.
 174  * @param   pcHashCollisions    Number of hash table insert collisions.
 175  * @param   pcHashCollisions2   Number of hash table secondary insert
 176  *                              collisions.
 177  * @param   pcHashInserts       Number of hash table inserts.
 178  * @param   pcRehashes          The number of rehashes.
 179  *
 180  * @remarks This is not a stable interface as it needs to reflect the cache
 181  *          implementation.
 182  */
 183 RTDECL(uint32_t) RTStrCacheGetStats(RTSTRCACHE hStrCache, size_t *pcbStrings, size_t *pcbChunks, size_t *pcbBigEntries,
 184                                     uint32_t *pcHashCollisions, uint32_t *pcHashCollisions2, uint32_t *pcHashInserts,
 185                                     uint32_t *pcRehashes);
 186
 187 /**
 188  * Indicates whether this a real string cache or a cheap place holder.
 189  *
 190  * A real string cache will return the same address when a string is added
 191  * multiple times.
 192  *
 193  * @returns true / false.
 194  */
 195 RTDECL(bool) RTStrCacheIsRealImpl(void);
 196
 197
 198 RT_C_DECLS_END
 199
 200 #endif /* !IPRT_INCLUDED_strcache_h */
 201