xref: /aoo4110/main/sal/inc/rtl/alloc.h (revision b1cdbd2c)
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