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