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