VirtualBox

source: vbox/trunk/include/iprt/memcache.h

Last change on this file was 106061, checked in by vboxsync, 4 weeks 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.0 KB
Line 
1/** @file
2 * IPRT - Memory Object Allocation Cache.
3 */
4
5/*
6 * Copyright (C) 2006-2024 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_memcache_h
37#define IPRT_INCLUDED_memcache_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42
43#include <iprt/cdefs.h>
44#include <iprt/types.h>
45
46RT_C_DECLS_BEGIN
47
48
49/** @defgroup grp_rt_memcache RTMemCache - Memory Object Allocation Cache
50 * @ingroup grp_rt
51 *
52 * Optimized allocation, initialization, freeing and destruction of memory
53 * objects of the same kind and size. Objects are constructed once, then
54 * allocated and freed one or more times, until finally destructed together with
55 * the cache (RTMemCacheDestroy). It's expected behavior, even when pfnCtor is
56 * NULL, that the user will be store information that should be persistent
57 * across RTMemCacheFree calls.
58 *
59 * The objects are zeroed prior to calling pfnCtor. For obvious reasons, the
60 * objects are not touched by the cache after that, so that RTMemCacheAlloc will
61 * return the object in the same state as when it as handed to RTMemCacheFree.
62 *
63 * @todo A callback for the reuse (at alloc time) might be of interest.
64 *
65 * @{
66 */
67
68/** A memory cache handle. */
69typedef R3R0PTRTYPE(struct RTMEMCACHEINT *) RTMEMCACHE;
70/** Pointer to a memory cache handle. */
71typedef RTMEMCACHE *PRTMEMCACHE;
72/** Nil memory cache handle. */
73#define NIL_RTMEMCACHE ((RTMEMCACHE)0)
74
75
76/**
77 * Object constructor.
78 *
79 * This is called for when an element is allocated for the first time.
80 *
81 * @returns IPRT status code.
82 * @param hMemCache The cache handle.
83 * @param pvObj The memory object that should be initialized.
84 * @param pvUser The user argument.
85 *
86 * @remarks No serialization is performed.
87 */
88typedef DECLCALLBACKTYPE(int, FNMEMCACHECTOR,(RTMEMCACHE hMemCache, void *pvObj, void *pvUser));
89/** Pointer to an object constructor for the memory cache. */
90typedef FNMEMCACHECTOR *PFNMEMCACHECTOR;
91
92/**
93 * Object destructor.
94 *
95 * This is called when we're shrinking or destroying the cache.
96 *
97 * @param hMemCache The cache handle.
98 * @param pvObj The memory object that should be initialized.
99 * @param pvUser The user argument.
100 *
101 * @remarks No serialization is performed.
102 */
103typedef DECLCALLBACKTYPE(void, FNMEMCACHEDTOR,(RTMEMCACHE hMemCache, void *pvObj, void *pvUser));
104/** Pointer to an object destructor for the memory cache. */
105typedef FNMEMCACHEDTOR *PFNMEMCACHEDTOR;
106
107
108/**
109 * Create an allocation cache for fixed size memory objects.
110 *
111 * @returns IPRT status code.
112 * @param phMemCache Where to return the cache handle.
113 * @param cbObject The size of one memory object.
114 * @param cbAlignment The object alignment. This must be a power of
115 * two. The higest alignment is 64. If set to 0,
116 * a sensible alignment value will be derived from
117 * the object size.
118 * @param cMaxObjects The maximum cache size. Pass UINT32_MAX if unsure.
119 * @param pfnCtor Object constructor callback. Optional.
120 * @param pfnDtor Object destructor callback. Optional.
121 * @param pvUser User argument for the two callbacks.
122 * @param fFlags Flags reserved for future use. Must be zero.
123 */
124RTDECL(int) RTMemCacheCreate(PRTMEMCACHE phMemCache, size_t cbObject, size_t cbAlignment, uint32_t cMaxObjects,
125 PFNMEMCACHECTOR pfnCtor, PFNMEMCACHEDTOR pfnDtor, void *pvUser, uint32_t fFlags);
126
127/**
128 * Destroy a cache destroying and freeing allocated memory.
129 *
130 * @returns IPRT status code.
131 * @param hMemCache The cache handle. NIL is quietly (VINF_SUCCESS)
132 * ignored.
133 */
134RTDECL(int) RTMemCacheDestroy(RTMEMCACHE hMemCache);
135
136/**
137 * Allocate an object.
138 *
139 * @returns Pointer to the allocated cache object.
140 * @param hMemCache The cache handle.
141 */
142RTDECL(void *) RTMemCacheAlloc(RTMEMCACHE hMemCache);
143
144/**
145 * Allocate an object and return a proper status code.
146 *
147 * @returns IPRT status code.
148 * @retval VERR_MEM_CACHE_MAX_SIZE if we've reached maximum size (see
149 * RTMemCacheCreate).
150 * @retval VERR_NO_MEMORY if we failed to allocate more memory for the cache.
151 *
152 * @param hMemCache The cache handle.
153 * @param ppvObj Where to return the object.
154 */
155RTDECL(int) RTMemCacheAllocEx(RTMEMCACHE hMemCache, void **ppvObj);
156
157/**
158 * Free an object previously returned by RTMemCacheAlloc or RTMemCacheAllocEx.
159 *
160 * @param hMemCache The cache handle.
161 * @param pvObj The object to free. NULL is fine.
162 */
163RTDECL(void) RTMemCacheFree(RTMEMCACHE hMemCache, void *pvObj);
164
165/** @} */
166
167RT_C_DECLS_END
168
169#endif /* !IPRT_INCLUDED_memcache_h */
170
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