/************************************************************** * * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, * software distributed under the License is distributed on an * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. * *************************************************************/ #ifndef _RTL_ALLOC_H_ #define _RTL_ALLOC_H_ # include #ifdef __cplusplus extern "C" { #endif /** Allocate memory. @descr A call to this function will return NULL upon the requested memory size being either zero or larger than currently allocatable. @param Bytes [in] memory size. @return pointer to allocated memory. */ void * SAL_CALL rtl_allocateMemory ( sal_Size Bytes ) SAL_THROW_EXTERN_C(); /** Reallocate memory. @descr A call to this function with parameter 'Ptr' being NULL is equivalent to a rtl_allocateMemory() call. A call to this function with parameter 'Bytes' being 0 is equivalent to a rtl_freeMemory() call. @see rtl_allocateMemory() @see rtl_freeMemory() @param Ptr [in] pointer to previously allocated memory. @param Bytes [in] new memory size. @return pointer to reallocated memory. May differ from Ptr. */ void * SAL_CALL rtl_reallocateMemory ( void * Ptr, sal_Size Bytes ) SAL_THROW_EXTERN_C(); /** Free memory. @param Ptr [in] pointer to previously allocated memory. @return none. Memory is released. Ptr is invalid. */ void SAL_CALL rtl_freeMemory ( void * Ptr ) SAL_THROW_EXTERN_C(); /** Allocate and zero memory. @descr A call to this function will return NULL upon the requested memory size being either zero or larger than currently allocatable. @param Bytes [in] memory size. @return pointer to allocated and zero'ed memory. */ void * SAL_CALL rtl_allocateZeroMemory ( sal_Size Bytes ) SAL_THROW_EXTERN_C(); /** Zero and free memory. @param Ptr [in] pointer to previously allocated memory. @param Bytes [in] memory size. @return none. Memory is zero'ed and released. Ptr is invalid. */ void SAL_CALL rtl_freeZeroMemory ( void * Ptr, sal_Size Bytes ) SAL_THROW_EXTERN_C(); /** Opaque rtl_arena_type. */ typedef struct rtl_arena_st rtl_arena_type; #define RTL_ARENA_NAME_LENGTH 31 /** rtl_arena_create() * * @param pName [in] descriptive name; for debugging purposes. * @param quantum [in] resource allocation unit / granularity; rounded up to next power of 2. * @param quantum_cache_max [in] max resources to cache; rounded up to next multiple of quantum; usually 0. * @param source_arena [in] passed as argument to source_alloc, source_free; usually NULL. * @param source_alloc [in] function to allocate resources; usually rtl_arena_alloc. * @param source_free [in] function to free resources; usually rtl_arena_free. * @param nFlags [in] flags; usually 0. * * @return pointer to rtl_arena_type, or NULL upon failure. * * @see rtl_arena_destroy() */ rtl_arena_type * SAL_CALL rtl_arena_create ( const char * pName, sal_Size quantum, sal_Size quantum_cache_max, rtl_arena_type * source_arena, void * (SAL_CALL * source_alloc)(rtl_arena_type *, sal_Size *), void (SAL_CALL * source_free) (rtl_arena_type *, void *, sal_Size), int nFlags ) SAL_THROW_EXTERN_C(); /** rtl_arena_destroy() * * @param pArena [in] the arena to destroy. * @return None * * @see rtl_arena_create() */ void SAL_CALL rtl_arena_destroy ( rtl_arena_type * pArena ) SAL_THROW_EXTERN_C(); /** rtl_arena_alloc() * * @param pArena [in] arena from which resource is allocated. * @param pBytes [inout] size of resource to allocate. * * @return allocated resource, or NULL upon failure. * * @see rtl_arena_free() */ void * SAL_CALL rtl_arena_alloc ( rtl_arena_type * pArena, sal_Size * pBytes ) SAL_THROW_EXTERN_C(); /** rtl_arena_free() * * @param pArena [in] arena from which resource was allocated. * @param pAddr [in] resource to free. * @param nBytes [in] size of resource. * * @return None. * * @see rtl_arena_alloc() */ void SAL_CALL rtl_arena_free ( rtl_arena_type * pArena, void * pAddr, sal_Size nBytes ) SAL_THROW_EXTERN_C(); /** Opaque rtl_cache_type. */ typedef struct rtl_cache_st rtl_cache_type; #define RTL_CACHE_NAME_LENGTH 31 #define RTL_CACHE_FLAG_BULKDESTROY 1 /** rtl_cache_create() * * @param pName [in] descriptive name; for debugging purposes. * @param nObjSize [in] object size. * @param nObjAlign [in] object alignment; usually 0 for suitable default. * @param constructor [in] object constructor callback function; returning 1 for success or 0 for failure. * @param destructor [in] object destructor callback function. * @param reclaim [in] reclaim callback function. * @param pUserArg [in] opaque argument passed to callback functions. * @param nFlags [in] flags. * * @return pointer to rtl_cache_type, or NULL upon failure. * * @see rtl_cache_destroy() */ rtl_cache_type * SAL_CALL rtl_cache_create ( const char * pName, sal_Size nObjSize, sal_Size nObjAlign, int (SAL_CALL * constructor)(void * pObj, void * pUserArg), void (SAL_CALL * destructor) (void * pObj, void * pUserArg), void (SAL_CALL * reclaim) (void * pUserArg), void * pUserArg, rtl_arena_type * pSource, int nFlags ) SAL_THROW_EXTERN_C(); /** rtl_cache_destroy() * * @param pCache [in] the cache to destroy. * * @return None. * * @see rtl_cache_create() */ void SAL_CALL rtl_cache_destroy ( rtl_cache_type * pCache ) SAL_THROW_EXTERN_C(); /** rtl_cache_alloc() * * @param pCache [in] cache from which object is allocated. * * @return pointer to allocated object, or NULL upon failure. */ void * SAL_CALL rtl_cache_alloc ( rtl_cache_type * pCache ) SAL_THROW_EXTERN_C(); /** rtl_cache_free() * * @param pCache [in] cache from which object was allocated. * @param pObj [in] object to free. * * @return None. * * @see rtl_cache_alloc() */ void SAL_CALL rtl_cache_free ( rtl_cache_type * pCache, void * pObj ) SAL_THROW_EXTERN_C(); #ifdef __cplusplus } #endif #endif /*_RTL_ALLOC_H_ */