Changeset 26416 in vbox for trunk/include

Timestamp:

Feb 10, 2010 4:32:22 PM (15 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

57519

Message:

RTMemCache: Initial coding (completely untested).

Location:

trunk/include/iprt

Files:

• err.h (modified) (1 diff)
• memcache.h (modified) (2 diffs)

trunk/include/iprt/err.h

@@ -1205 +1205 @@
 /** @} */
 
+/** @name RTMemCache status codes
+ * @{ */
+/** Reached the max cache size. */
+#define VERR_MEM_CACHE_MAX_SIZE                 (-855)
+/** @} */
+
 /** @name RTS3 status codes
  * @{ */

trunk/include/iprt/memcache.h

@@ -4 +4 @@
 
 /*
- * Copyright (C) 2006-2007 Sun Microsystems, Inc.
+ * Copyright (C) 2006-2010 Sun Microsystems, Inc.
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as
@@ -47 +47 @@
  */
 
-/** @todo Specify and implement RTMemCache. (This header is just a reminder.) */
+/** 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 DECLCALLBACK(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 DECLCALLBACK(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.
+ */
+RTDECL(int)     RTMemCacheCreate(PRTMEMCACHE phMemCache, size_t cbObject, uint32_t cMaxObjects,
+                                 PFNMEMCACHECTOR pfnCtor, PFNMEMCACHEDTOR pfnDtor, void *pvUser);
+
+/**
+ * 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);
 
 /** @} */