sal/inc/rtl/alloc.h

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: alloc.h,v $
  10  * $Revision: 1.9 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef _RTL_ALLOC_H_
  32 #define _RTL_ALLOC_H_
  33
  34 #       include <sal/types.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40
  41 /** Allocate memory.
  42     @descr A call to this function will return NULL upon the requested
  43     memory size being either zero or larger than currently allocatable.
  44
  45     @param  Bytes [in] memory size.
  46     @return pointer to allocated memory.
  47  */
  48 void * SAL_CALL rtl_allocateMemory (
  49     sal_Size Bytes
  50 ) SAL_THROW_EXTERN_C();
  51
  52
  53 /** Reallocate memory.
  54     @descr A call to this function with parameter 'Ptr' being NULL
  55     is equivalent to a rtl_allocateMemory() call.
  56
  57     A call to this function with parameter 'Bytes' being 0
  58     is equivalent to a rtl_freeMemory() call.
  59
  60     @see rtl_allocateMemory()
  61     @see rtl_freeMemory()
  62
  63     @param  Ptr   [in] pointer to previously allocated memory.
  64     @param  Bytes [in] new memory size.
  65     @return pointer to reallocated memory. May differ from Ptr.
  66  */
  67 void * SAL_CALL rtl_reallocateMemory (
  68     void *   Ptr,
  69     sal_Size Bytes
  70 ) SAL_THROW_EXTERN_C();
  71
  72
  73 /** Free memory.
  74     @param  Ptr   [in] pointer to previously allocated memory.
  75     @return none. Memory is released. Ptr is invalid.
  76  */
  77 void SAL_CALL rtl_freeMemory (
  78     void * Ptr
  79 ) SAL_THROW_EXTERN_C();
  80
  81
  82 /** Allocate and zero memory.
  83     @descr A call to this function will return NULL upon the requested
  84     memory size being either zero or larger than currently allocatable.
  85
  86     @param  Bytes [in] memory size.
  87     @return pointer to allocated and zero'ed memory.
  88  */
  89 void * SAL_CALL rtl_allocateZeroMemory (
  90     sal_Size Bytes
  91 ) SAL_THROW_EXTERN_C();
  92
  93
  94 /** Zero and free memory.
  95     @param  Ptr   [in] pointer to previously allocated memory.
  96     @param  Bytes [in] memory size.
  97     @return none. Memory is zero'ed and released. Ptr is invalid.
  98  */
  99 void SAL_CALL rtl_freeZeroMemory (
 100     void *   Ptr,
 101     sal_Size Bytes
 102 ) SAL_THROW_EXTERN_C();
 103
 104
 105 /** Opaque rtl_arena_type.
 106  */
 107 typedef struct rtl_arena_st rtl_arena_type;
 108
 109 #define RTL_ARENA_NAME_LENGTH 31
 110
 111
 112 /** rtl_arena_create()
 113  *
 114  *  @param  pName             [in] descriptive name; for debugging purposes.
 115  *  @param  quantum           [in] resource allocation unit / granularity; rounded up to next power of 2.
 116  *  @param  quantum_cache_max [in] max resources to cache; rounded up to next multiple of quantum; usually 0.
 117  *  @param  source_arena      [in] passed as argument to source_alloc, source_free; usually NULL.
 118  *  @param  source_alloc      [in] function to allocate resources; usually rtl_arena_alloc.
 119  *  @param  source_free       [in] function to free resources; usually rtl_arena_free.
 120  *  @param  nFlags            [in] flags; usually 0.
 121  *
 122  *  @return pointer to rtl_arena_type, or NULL upon failure.
 123  *
 124  *  @see rtl_arena_destroy()
 125  */
 126 rtl_arena_type *
 127 SAL_CALL rtl_arena_create (
 128     const char *       pName,
 129     sal_Size           quantum,
 130     sal_Size           quantum_cache_max,
 131     rtl_arena_type *   source_arena,
 132     void * (SAL_CALL * source_alloc)(rtl_arena_type *, sal_Size *),
 133     void   (SAL_CALL * source_free) (rtl_arena_type *, void *, sal_Size),
 134     int                nFlags
 135 ) SAL_THROW_EXTERN_C();
 136
 137
 138 /** rtl_arena_destroy()
 139  *
 140  *  @param  pArena [in] the arena to destroy.
 141  *  @return None
 142  *
 143  *  @see rtl_arena_create()
 144  */
 145 void
 146 SAL_CALL rtl_arena_destroy (
 147     rtl_arena_type * pArena
 148 ) SAL_THROW_EXTERN_C();
 149
 150
 151 /** rtl_arena_alloc()
 152  *
 153  *  @param  pArena [in]    arena from which resource is allocated.
 154  *  @param  pBytes [inout] size of resource to allocate.
 155  *
 156  *  @return allocated resource, or NULL upon failure.
 157  *
 158  *  @see rtl_arena_free()
 159  */
 160 void *
 161 SAL_CALL rtl_arena_alloc (
 162     rtl_arena_type * pArena,
 163     sal_Size *       pBytes
 164 ) SAL_THROW_EXTERN_C();
 165
 166
 167 /** rtl_arena_free()
 168  *
 169  *  @param  pArena [in] arena from which resource was allocated.
 170  *  @param  pAddr  [in] resource to free.
 171  *  @param  nBytes [in] size of resource.
 172  *
 173  *  @return None.
 174  *
 175  *  @see rtl_arena_alloc()
 176  */
 177 void
 178 SAL_CALL rtl_arena_free (
 179     rtl_arena_type * pArena,
 180     void *           pAddr,
 181     sal_Size         nBytes
 182 ) SAL_THROW_EXTERN_C();
 183
 184
 185 /** Opaque rtl_cache_type.
 186  */
 187 typedef struct rtl_cache_st rtl_cache_type;
 188
 189 #define RTL_CACHE_NAME_LENGTH 31
 190
 191 #define RTL_CACHE_FLAG_BULKDESTROY 1
 192
 193 /** rtl_cache_create()
 194  *
 195  *  @param  pName       [in] descriptive name; for debugging purposes.
 196  *  @param  nObjSize    [in] object size.
 197  *  @param  nObjAlign   [in] object alignment; usually 0 for suitable default.
 198  *  @param  constructor [in] object constructor callback function; returning 1 for success or 0 for failure.
 199  *  @param  destructor  [in] object destructor callback function.
 200  *  @param  reclaim     [in] reclaim callback function.
 201  *  @param  pUserArg    [in] opaque argument passed to callback functions.
 202  *  @param  nFlags      [in] flags.
 203  *
 204  *  @return pointer to rtl_cache_type, or NULL upon failure.
 205  *
 206  *  @see rtl_cache_destroy()
 207  */
 208 rtl_cache_type *
 209 SAL_CALL rtl_cache_create (
 210     const char *     pName,
 211     sal_Size         nObjSize,
 212     sal_Size         nObjAlign,
 213     int  (SAL_CALL * constructor)(void * pObj, void * pUserArg),
 214     void (SAL_CALL * destructor) (void * pObj, void * pUserArg),
 215     void (SAL_CALL * reclaim)    (void * pUserArg),
 216     void *           pUserArg,
 217     rtl_arena_type * pSource,
 218     int              nFlags
 219 ) SAL_THROW_EXTERN_C();
 220
 221
 222 /** rtl_cache_destroy()
 223  *
 224  *  @param  pCache [in] the cache to destroy.
 225  *
 226  *  @return None.
 227  *
 228  *  @see rtl_cache_create()
 229  */
 230 void
 231 SAL_CALL rtl_cache_destroy (
 232     rtl_cache_type * pCache
 233 ) SAL_THROW_EXTERN_C();
 234
 235
 236 /** rtl_cache_alloc()
 237  *
 238  *  @param  pCache [in] cache from which object is allocated.
 239  *
 240  *  @return pointer to allocated object, or NULL upon failure.
 241  */
 242 void *
 243 SAL_CALL rtl_cache_alloc (
 244     rtl_cache_type * pCache
 245 ) SAL_THROW_EXTERN_C();
 246
 247
 248 /** rtl_cache_free()
 249  *
 250  *  @param  pCache [in] cache from which object was allocated.
 251  *  @param  pObj   [in] object to free.
 252  *
 253  *  @return None.
 254  *
 255  *  @see rtl_cache_alloc()
 256  */
 257 void
 258 SAL_CALL rtl_cache_free (
 259     rtl_cache_type * pCache,
 260     void *           pObj
 261 ) SAL_THROW_EXTERN_C();
 262
 263
 264 #ifdef __cplusplus
 265 }
 266 #endif
 267
 268 #endif /*_RTL_ALLOC_H_ */
 269