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
|
/** @file
* IPRT - Memory Object Allocation Cache.
*/
/*
* Copyright (C) 2006-2025 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_memcache_h
#define IPRT_INCLUDED_memcache_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif
#include <iprt/cdefs.h>
#include <iprt/types.h>
RT_C_DECLS_BEGIN
/** @defgroup grp_rt_memcache RTMemCache - Memory Object Allocation Cache
* @ingroup grp_rt
*
* Optimized allocation, initialization, freeing and destruction of memory
* objects of the same kind and size. Objects are constructed once, then
* allocated and freed one or more times, until finally destructed together with
* the cache (RTMemCacheDestroy). It's expected behavior, even when pfnCtor is
* NULL, that the user will be store information that should be persistent
* across RTMemCacheFree calls.
*
* The objects are zeroed prior to calling pfnCtor. For obvious reasons, the
* objects are not touched by the cache after that, so that RTMemCacheAlloc will
* return the object in the same state as when it as handed to RTMemCacheFree.
*
* @todo A callback for the reuse (at alloc time) might be of interest.
*
* @{
*/
/** A memory cache handle. */
typedef R3R0PTRTYPE(struct RTMEMCACHEINT *) RTMEMCACHE;
/** Pointer to a memory cache handle. */
typedef RTMEMCACHE *PRTMEMCACHE;
/** Nil memory cache handle. */
#define NIL_RTMEMCACHE ((RTMEMCACHE)0)
/**
* Object constructor.
*
* This is called for when an element is allocated for the first time.
*
* @returns IPRT status code.
* @param hMemCache The cache handle.
* @param pvObj The memory object that should be initialized.
* @param pvUser The user argument.
*
* @remarks No serialization is performed.
*/
typedef DECLCALLBACKTYPE(int, FNMEMCACHECTOR,(RTMEMCACHE hMemCache, void *pvObj, void *pvUser));
/** Pointer to an object constructor for the memory cache. */
typedef FNMEMCACHECTOR *PFNMEMCACHECTOR;
/**
* Object destructor.
*
* This is called when we're shrinking or destroying the cache.
*
* @param hMemCache The cache handle.
* @param pvObj The memory object that should be initialized.
* @param pvUser The user argument.
*
* @remarks No serialization is performed.
*/
typedef DECLCALLBACKTYPE(void, FNMEMCACHEDTOR,(RTMEMCACHE hMemCache, void *pvObj, void *pvUser));
/** Pointer to an object destructor for the memory cache. */
typedef FNMEMCACHEDTOR *PFNMEMCACHEDTOR;
/**
* Create an allocation cache for fixed size memory objects.
*
* @returns IPRT status code.
* @param phMemCache Where to return the cache handle.
* @param cbObject The size of one memory object.
* @param cbAlignment The object alignment. This must be a power of
* two. The higest alignment is 64. If set to 0,
* a sensible alignment value will be derived from
* the object size.
* @param cMaxObjects The maximum cache size. Pass UINT32_MAX if unsure.
* @param pfnCtor Object constructor callback. Optional.
* @param pfnDtor Object destructor callback. Optional.
* @param pvUser User argument for the two callbacks.
* @param fFlags Flags reserved for future use. Must be zero.
*/
RTDECL(int) RTMemCacheCreate(PRTMEMCACHE phMemCache, size_t cbObject, size_t cbAlignment, uint32_t cMaxObjects,
PFNMEMCACHECTOR pfnCtor, PFNMEMCACHEDTOR pfnDtor, void *pvUser, uint32_t fFlags);
/**
* Destroy a cache destroying and freeing allocated memory.
*
* @returns IPRT status code.
* @param hMemCache The cache handle. NIL is quietly (VINF_SUCCESS)
* ignored.
*/
RTDECL(int) RTMemCacheDestroy(RTMEMCACHE hMemCache);
/**
* Allocate an object.
*
* @returns Pointer to the allocated cache object.
* @param hMemCache The cache handle.
*/
RTDECL(void *) RTMemCacheAlloc(RTMEMCACHE hMemCache);
/**
* Allocate an object and return a proper status code.
*
* @returns IPRT status code.
* @retval VERR_MEM_CACHE_MAX_SIZE if we've reached maximum size (see
* RTMemCacheCreate).
* @retval VERR_NO_MEMORY if we failed to allocate more memory for the cache.
*
* @param hMemCache The cache handle.
* @param ppvObj Where to return the object.
*/
RTDECL(int) RTMemCacheAllocEx(RTMEMCACHE hMemCache, void **ppvObj);
/**
* Free an object previously returned by RTMemCacheAlloc or RTMemCacheAllocEx.
*
* @param hMemCache The cache handle.
* @param pvObj The object to free. NULL is fine.
*/
RTDECL(void) RTMemCacheFree(RTMEMCACHE hMemCache, void *pvObj);
/** @} */
RT_C_DECLS_END
#endif /* !IPRT_INCLUDED_memcache_h */
|
