VirtualBox

source: vbox/trunk/include/iprt/strcache.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.7 KB
Line 
1/* $Id: strcache.h 98103 2023-01-17 14:15:46Z vboxsync $ */
2/** @file
3 * IPRT - String Cache, stub implementation.
4 */
5
6/*
7 * Copyright (C) 2009-2023 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
45RT_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 */
56RTDECL(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 */
70RTDECL(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 */
87RTDECL(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 */
99RTDECL(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 */
116RTDECL(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 */
128RTDECL(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 */
137RTDECL(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 */
148RTDECL(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 */
157RTDECL(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 */
183RTDECL(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 */
195RTDECL(bool) RTStrCacheIsRealImpl(void);
196
197
198RT_C_DECLS_END
199
200#endif /* !IPRT_INCLUDED_strcache_h */
201
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette