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