AOO410/main/sal/inc/rtl/alloc.h - openoffice - Git at Google

 /**************************************************************
  *
  * 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 <sal/types.h>

 #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_ */
	/**************************************************************
	*
	* 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 <sal/types.h>

	#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_ /