VirtualBox

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

Last change on this file since 80957 was 76585, checked in by vboxsync, 6 years ago

*: scm --fix-header-guard-endif

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