470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * IPRT - C++ Memory Resource Management.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * Copyright (C) 2006-2011 Oracle Corporation
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * available from http://www.virtualbox.org. This file is free software;
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * you can redistribute it and/or modify it under the terms of the GNU
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * General Public License (GPL) as published by the Free Software
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * The contents of this file may alternatively be used under the terms
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * of the Common Development and Distribution License Version 1.0
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * VirtualBox OSE distribution, in which case the provisions of the
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * CDDL are applicable instead of those of the GPL.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * You may elect to license modified versions of this file under the
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * terms and conditions of either the GPL or the CDDL or both.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync/** @defgroup grp_rt_cpp_autores_mem C++ Memory Resource Management
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @ingroup grp_rt_cpp_autores
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * Template function wrapping RTMemFree to get the correct a_fnDestruct
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * signature for RTCAutoRes.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * We can't use a more complex template here, because the g++ on RHEL 3
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * chokes on it with an internal compiler error.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @tparam T The data type that's being managed.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @param aMem Pointer to the memory that should be free.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsyncinline void RTCMemAutoDestructor(T *aMem) RT_NO_THROW
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * RTCMemAutoPtr allocator which uses RTMemTmpAlloc().
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @returns Allocated memory on success, NULL on failure.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @param pvOld What to reallocate, shall always be NULL.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @param cbNew The amount of memory to allocate (in bytes).
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsyncinline void *RTCMemTmpAutoAllocator(void *pvOld, size_t cbNew) RT_NO_THROW
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * Template function wrapping RTMemTmpFree to get the correct a_fnDestruct
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * signature for RTCAutoRes.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * We can't use a more complex template here, because the g++ on RHEL 3
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * chokes on it with an internal compiler error.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @tparam T The data type that's being managed.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @param aMem Pointer to the memory that should be free.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsyncinline void RTCMemTmpAutoDestructor(T *aMem) RT_NO_THROW
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * Template function wrapping RTMemEfFree to get the correct a_fnDestruct
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * signature for RTCAutoRes.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * We can't use a more complex template here, because the g++ on RHEL 3
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * chokes on it with an internal compiler error.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @tparam T The data type that's being managed.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @param aMem Pointer to the memory that should be free.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * Template function wrapping NULL to get the correct NilRes signature
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * for RTCAutoRes.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @tparam T The data type that's being managed.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @returns NULL with the right type.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync return (T *)(NULL);
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * An auto pointer-type template class for managing memory allocating
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * via C APIs like RTMem (the default).
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * The main purpose of this class is to automatically free memory that
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * isn't explicitly used (release()'ed) when the object goes out of scope.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * As an additional service it can also make the allocations and
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * reallocations for you if you like, but it can also take of memory
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * you hand it.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @tparam T The data type to manage allocations for.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @tparam a_fnDestruct The function to be used to free the resource.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * This will default to RTMemFree.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @tparam a_fnAllocator The function to be used to allocate or reallocate
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * the managed memory.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * This is standard realloc() like stuff, so it's
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * possible to support simple allocation without
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * actually having to support reallocating memory if
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * that's a problem. This will default to
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * RTMemRealloc.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync# if defined(RTMEM_WRAP_TO_EF_APIS) && !defined(RTMEM_NO_WRAP_TO_EF_APIS)
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync void *a_fnAllocator(void *, size_t, const char *) = RTMemEfReallocNP
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync void *a_fnAllocator(void *, size_t, const char *) = RTMemReallocTag
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync : public RTCAutoRes<T *, a_fnDestruct, RTCMemAutoNil<T> >
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * Constructor.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @param aPtr Memory pointer to manage. Defaults to NULL.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync : RTCAutoRes<T *, a_fnDestruct, RTCMemAutoNil<T> >(aPtr)
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * Constructor that allocates memory.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @param a_cElements The number of elements (of the data type) to allocate.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @param a_fZeroed Whether the memory should be memset with zeros after
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * the allocation. Defaults to false.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync RTCMemAutoPtr(size_t a_cElements, bool a_fZeroed = false)
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync : RTCAutoRes<T *, a_fnDestruct, RTCMemAutoNil<T> >((T *)a_fnAllocator(NULL, a_cElements * sizeof(T), RTMEM_TAG))
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync memset(this->get(), '\0', a_cElements * sizeof(T));
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * Free current memory and start managing aPtr.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @param aPtr Memory pointer to manage.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync this->RTCAutoRes<T *, a_fnDestruct, RTCMemAutoNil<T> >::operator=(aPtr);
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * Dereference with * operator.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * Dereference with -> operator.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * Accessed with the subscript operator ([]).
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @returns Reference to the element.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @param a_i The element to access.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * Allocates memory and start manage it.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * Any previously managed memory will be freed before making
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * the new allocation.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @returns Success indicator.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @retval true if the new allocation succeeds.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @retval false on failure, no memory is associated with the object.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @param a_cElements The number of elements (of the data type) to allocate.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * This defaults to 1.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @param a_fZeroed Whether the memory should be memset with zeros after
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * the allocation. Defaults to false.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync bool alloc(size_t a_cElements = 1, bool a_fZeroed = false)
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync T *pNewMem = (T *)a_fnAllocator(NULL, a_cElements * sizeof(T), RTMEM_TAG);
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * Reallocate or allocates the memory resource.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * Free the old value if allocation fails.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * The content of any additional memory that was allocated is
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * undefined when using the default allocator.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @returns Success indicator.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @retval true if the new allocation succeeds.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @retval false on failure, no memory is associated with the object.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * @param a_cElements The new number of elements (of the data type) to
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * allocate. The size of the allocation is the number of
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * elements times the size of the data type - this is
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * currently what's passed down to the a_fnAllocator.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync * This defaults to 1.
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync T *aNewValue = (T *)a_fnAllocator(this->get(), a_cElements * sizeof(T), RTMEM_TAG);
470122d12fa43f83f993ae8e93ba8e3cf4c674cdvboxsync /* We want this both if aNewValue is non-NULL and if it is NULL. */