20593760b116c90f3e439552763eef632a3bbb17vboxsync * IPRT - Memory Allocation Pool.
c7814cf6e1240a519cbec0441e033d0e2470ed00vboxsync * Copyright (C) 2009-2010 Oracle Corporation
20593760b116c90f3e439552763eef632a3bbb17vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
20593760b116c90f3e439552763eef632a3bbb17vboxsync * available from http://www.virtualbox.org. This file is free software;
20593760b116c90f3e439552763eef632a3bbb17vboxsync * you can redistribute it and/or modify it under the terms of the GNU
20593760b116c90f3e439552763eef632a3bbb17vboxsync * General Public License (GPL) as published by the Free Software
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
20593760b116c90f3e439552763eef632a3bbb17vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
20593760b116c90f3e439552763eef632a3bbb17vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * The contents of this file may alternatively be used under the terms
20593760b116c90f3e439552763eef632a3bbb17vboxsync * of the Common Development and Distribution License Version 1.0
20593760b116c90f3e439552763eef632a3bbb17vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20593760b116c90f3e439552763eef632a3bbb17vboxsync * VirtualBox OSE distribution, in which case the provisions of the
20593760b116c90f3e439552763eef632a3bbb17vboxsync * CDDL are applicable instead of those of the GPL.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * You may elect to license modified versions of this file under the
20593760b116c90f3e439552763eef632a3bbb17vboxsync * terms and conditions of either the GPL or the CDDL or both.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Creates a new memory pool.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns IPRT status code.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param phMemPool Where to return the handle to the new memory
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param pszName The name of the pool (for debug purposes).
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(int) RTMemPoolCreate(PRTMEMPOOL phMemPool, const char *pszName);
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Destroys the specified pool, freeing all the memory it contains.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns IPRT status code.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param hMemPool The handle to the pool. The nil handle and
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * RTMEMPOOL_DEFAULT are quietly ignored (retval
20593760b116c90f3e439552763eef632a3bbb17vboxsync * VINF_SUCCESS).
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Allocates memory.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns Pointer to the allocated memory.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns NULL on failure.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param hMemPool Handle to the pool to allocate the memory from.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param cb Size in bytes of the memory block to allocated.
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(void *) RTMemPoolAlloc(RTMEMPOOL hMemPool, size_t cb) RT_NO_THROW;
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * Allocates zero'd memory.
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * Instead of memset(pv, 0, sizeof()) use this when you want zero'd
20593760b116c90f3e439552763eef632a3bbb17vboxsync * memory. This keeps the code smaller and the heap can skip the memset
20593760b116c90f3e439552763eef632a3bbb17vboxsync * in about 0.42% of calls :-).
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns Pointer to the allocated memory.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns NULL on failure.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param hMemPool Handle to the pool to allocate the memory from.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param cb Size in bytes of the memory block to allocated.
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(void *) RTMemPoolAllocZ(RTMEMPOOL hMemPool, size_t cb) RT_NO_THROW;
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Duplicates a chunk of memory into a new heap block.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns New heap block with the duplicate data.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns NULL if we're out of memory.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param hMemPool Handle to the pool to allocate the memory from.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param pvSrc The memory to duplicate.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param cb The amount of memory to duplicate.
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(void *) RTMemPoolDup(RTMEMPOOL hMemPool, const void *pvSrc, size_t cb) RT_NO_THROW;
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Duplicates a chunk of memory into a new heap block with some
20593760b116c90f3e439552763eef632a3bbb17vboxsync * additional zeroed memory.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns New heap block with the duplicate data.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns NULL if we're out of memory.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param hMemPool Handle to the pool to allocate the memory from.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param pvSrc The memory to duplicate.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param cbSrc The amount of memory to duplicate.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param cbExtra The amount of extra memory to allocate and zero.
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(void *) RTMemPoolDupEx(RTMEMPOOL hMemPool, const void *pvSrc, size_t cbSrc, size_t cbExtra) RT_NO_THROW;
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Reallocates memory.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns Pointer to the allocated memory.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns NULL on failure.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param hMemPool Handle to the pool containing the old memory.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param pvOld The memory block to reallocate.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param cbNew The new block size (in bytes).
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(void *) RTMemPoolRealloc(RTMEMPOOL hMemPool, void *pvOld, size_t cbNew) RT_NO_THROW;
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Frees memory allocated from a pool.
3f286f1a573fddc997ce03a37282536899ec4446vboxsync * @param hMemPool Handle to the pool containing the memory. Passing
20593760b116c90f3e439552763eef632a3bbb17vboxsync * NIL here is fine, but it may come at a slight
20593760b116c90f3e439552763eef632a3bbb17vboxsync * performance cost.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param pv Pointer to memory block.
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * @remarks This is the same a RTMemPoolRelease but included here as a separate
20593760b116c90f3e439552763eef632a3bbb17vboxsync * function to simplify code migration.
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(void) RTMemPoolFree(RTMEMPOOL hMemPool, void *pv) RT_NO_THROW;
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * Retains a reference to a memory block in a pool.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns New reference count, UINT32_MAX on error (asserted).
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param pv Pointer to memory block.
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(uint32_t) RTMemPoolRetain(void *pv) RT_NO_THROW;
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Releases a reference to a memory block in a pool.
3f286f1a573fddc997ce03a37282536899ec4446vboxsync * @returns New reference count, UINT32_MAX on error (asserted).
3f286f1a573fddc997ce03a37282536899ec4446vboxsync * @param hMemPool Handle to the pool containing the memory. Passing
20593760b116c90f3e439552763eef632a3bbb17vboxsync * NIL here is fine, but it may come at a slight
20593760b116c90f3e439552763eef632a3bbb17vboxsync * performance cost.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param pv Pointer to memory block.
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(uint32_t) RTMemPoolRelease(RTMEMPOOL hMemPool, void *pv) RT_NO_THROW;
3f286f1a573fddc997ce03a37282536899ec4446vboxsync * Get the current reference count.
3f286f1a573fddc997ce03a37282536899ec4446vboxsync * @returns The reference count, UINT32_MAX on error (asserted).
3f286f1a573fddc997ce03a37282536899ec4446vboxsync * @param pv Pointer to memory block.