include/iprt/memcache.h

   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
  46 RT_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. */
  69 typedef R3R0PTRTYPE(struct RTMEMCACHEINT *)     RTMEMCACHE;
  70 /** Pointer to a memory cache handle. */
  71 typedef 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  */
  88 typedef DECLCALLBACKTYPE(int, FNMEMCACHECTOR,(RTMEMCACHE hMemCache, void *pvObj, void *pvUser));
  89 /** Pointer to an object constructor for the memory cache. */
  90 typedef 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  */
 103 typedef DECLCALLBACKTYPE(void, FNMEMCACHEDTOR,(RTMEMCACHE hMemCache, void *pvObj, void *pvUser));
 104 /** Pointer to an object destructor for the memory cache. */
 105 typedef 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  */
 124 RTDECL(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  */
 134 RTDECL(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  */
 142 RTDECL(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  */
 155 RTDECL(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  */
 163 RTDECL(void)    RTMemCacheFree(RTMEMCACHE hMemCache, void *pvObj);
 164
 165 /** @} */
 166
 167 RT_C_DECLS_END
 168
 169 #endif /* !IPRT_INCLUDED_memcache_h */
 170