1 | /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ |
2 | /* |
3 | * This file is part of the LibreOffice project. |
4 | * |
5 | * This Source Code Form is subject to the terms of the Mozilla Public |
6 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
7 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. |
8 | * |
9 | * This file incorporates work covered by the following license notice: |
10 | * |
11 | * Licensed to the Apache Software Foundation (ASF) under one or more |
12 | * contributor license agreements. See the NOTICE file distributed |
13 | * with this work for additional information regarding copyright |
14 | * ownership. The ASF licenses this file to you under the Apache |
15 | * License, Version 2.0 (the "License"); you may not use this file |
16 | * except in compliance with the License. You may obtain a copy of |
17 | * the License at http://www.apache.org/licenses/LICENSE-2.0 . |
18 | */ |
19 | |
20 | #ifndef INCLUDED_RTL_ALLOC_H |
21 | #define INCLUDED_RTL_ALLOC_H |
22 | |
23 | #include <sal/config.h> |
24 | |
25 | #include <sal/saldllapi.h> |
26 | #include <sal/types.h> |
27 | |
28 | #ifdef __cplusplus |
29 | extern "C" { |
30 | #endif |
31 | |
32 | |
33 | /** Allocate memory. |
34 | |
35 | 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 | SAL_DLLPUBLIC void * SAL_CALL rtl_allocateMemory ( |
42 | sal_Size Bytes |
43 | ) SAL_THROW_EXTERN_C(); |
44 | |
45 | |
46 | /** Reallocate memory. |
47 | |
48 | A call to this function with parameter 'Ptr' being NULL |
49 | is equivalent to a rtl_allocateMemory() call. |
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 | SAL_DLLPUBLIC 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 | SAL_DLLPUBLIC void SAL_CALL rtl_freeMemory ( |
71 | void * Ptr |
72 | ) SAL_THROW_EXTERN_C(); |
73 | |
74 | |
75 | /** Allocate and zero memory. |
76 | |
77 | A call to this function will return NULL upon the requested |
78 | memory size being either zero or larger than currently allocatable. |
79 | |
80 | @param Bytes [in] memory size. |
81 | @return pointer to allocated and zero'ed memory. |
82 | */ |
83 | SAL_DLLPUBLIC void * SAL_CALL rtl_allocateZeroMemory ( |
84 | sal_Size Bytes |
85 | ) SAL_THROW_EXTERN_C(); |
86 | |
87 | |
88 | /** Zero and free memory. |
89 | @param Ptr [in] pointer to previously allocated memory. |
90 | @param Bytes [in] memory size. |
91 | @return none. Memory is zero'ed and released. Ptr is invalid. |
92 | */ |
93 | SAL_DLLPUBLIC void SAL_CALL rtl_freeZeroMemory ( |
94 | void * Ptr, |
95 | sal_Size Bytes |
96 | ) SAL_THROW_EXTERN_C(); |
97 | |
98 | |
99 | /** Opaque rtl_arena_type. |
100 | */ |
101 | typedef struct rtl_arena_st rtl_arena_type; |
102 | |
103 | #define RTL_ARENA_NAME_LENGTH 31 |
104 | |
105 | |
106 | /** rtl_arena_create() |
107 | * |
108 | * @param pName [in] descriptive name; for debugging purposes. |
109 | * @param quantum [in] resource allocation unit / granularity; rounded up to next power of 2. |
110 | * @param quantum_cache_max [in] max resources to cache; rounded up to next multiple of quantum; usually 0. |
111 | * @param source_arena [in] passed as argument to source_alloc, source_free; usually NULL. |
112 | * @param source_alloc [in] function to allocate resources; usually rtl_arena_alloc. |
113 | * @param source_free [in] function to free resources; usually rtl_arena_free. |
114 | * @param nFlags [in] flags; usually 0. |
115 | * |
116 | * @return pointer to rtl_arena_type, or NULL upon failure. |
117 | * |
118 | * @see rtl_arena_destroy() |
119 | */ |
120 | SAL_DLLPUBLIC rtl_arena_type * 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 | SAL_DLLPUBLIC void SAL_CALL rtl_arena_destroy ( |
139 | rtl_arena_type * pArena |
140 | ) SAL_THROW_EXTERN_C(); |
141 | |
142 | |
143 | /** rtl_arena_alloc() |
144 | * |
145 | * @param pArena [in] arena from which resource is allocated. |
146 | * @param pBytes [inout] size of resource to allocate. |
147 | * |
148 | * @return allocated resource, or NULL upon failure. |
149 | * |
150 | * @see rtl_arena_free() |
151 | */ |
152 | SAL_DLLPUBLIC void * SAL_CALL rtl_arena_alloc ( |
153 | rtl_arena_type * pArena, |
154 | sal_Size * pBytes |
155 | ) SAL_THROW_EXTERN_C(); |
156 | |
157 | |
158 | /** rtl_arena_free() |
159 | * |
160 | * @param pArena [in] arena from which resource was allocated. |
161 | * @param pAddr [in] resource to free. |
162 | * @param nBytes [in] size of resource. |
163 | * |
164 | * @return None. |
165 | * |
166 | * @see rtl_arena_alloc() |
167 | */ |
168 | SAL_DLLPUBLIC void SAL_CALL rtl_arena_free ( |
169 | rtl_arena_type * pArena, |
170 | void * pAddr, |
171 | sal_Size nBytes |
172 | ) SAL_THROW_EXTERN_C(); |
173 | |
174 | |
175 | /** Opaque rtl_cache_type. |
176 | */ |
177 | typedef struct rtl_cache_st rtl_cache_type; |
178 | |
179 | #define RTL_CACHE_NAME_LENGTH 31 |
180 | |
181 | #define RTL_CACHE_FLAG_BULKDESTROY 1 |
182 | |
183 | /** rtl_cache_create() |
184 | * |
185 | * @param pName [in] descriptive name; for debugging purposes. |
186 | * @param nObjSize [in] object size. |
187 | * @param nObjAlign [in] object alignment; usually 0 for suitable default. |
188 | * @param constructor [in] object constructor callback function; returning 1 for success or 0 for failure. |
189 | * @param destructor [in] object destructor callback function. |
190 | * @param reclaim [in] reclaim callback function. |
191 | * @param pUserArg [in] opaque argument passed to callback functions. |
192 | * @param pSource [in] opaque argument passed to callback functions. |
193 | * @param nFlags [in] flags. |
194 | * |
195 | * @return pointer to rtl_cache_type, or NULL upon failure. |
196 | * |
197 | * @see rtl_cache_destroy() |
198 | */ |
199 | SAL_DLLPUBLIC rtl_cache_type * SAL_CALL rtl_cache_create ( |
200 | const char * pName, |
201 | sal_Size nObjSize, |
202 | sal_Size nObjAlign, |
203 | int (SAL_CALL * constructor)(void * pObj, void * pUserArg), |
204 | void (SAL_CALL * destructor) (void * pObj, void * pUserArg), |
205 | void (SAL_CALL * reclaim) (void * pUserArg), |
206 | void * pUserArg, |
207 | rtl_arena_type * pSource, |
208 | int nFlags |
209 | ) SAL_THROW_EXTERN_C(); |
210 | |
211 | |
212 | /** rtl_cache_destroy() |
213 | * |
214 | * @param pCache [in] the cache to destroy. |
215 | * |
216 | * @return None. |
217 | * |
218 | * @see rtl_cache_create() |
219 | */ |
220 | SAL_DLLPUBLIC void SAL_CALL rtl_cache_destroy ( |
221 | rtl_cache_type * pCache |
222 | ) SAL_THROW_EXTERN_C(); |
223 | |
224 | |
225 | /** rtl_cache_alloc() |
226 | * |
227 | * @param pCache [in] cache from which object is allocated. |
228 | * |
229 | * @return pointer to allocated object, or NULL upon failure. |
230 | */ |
231 | SAL_DLLPUBLIC void * SAL_CALL rtl_cache_alloc ( |
232 | rtl_cache_type * pCache |
233 | ) SAL_THROW_EXTERN_C(); |
234 | |
235 | |
236 | /** rtl_cache_free() |
237 | * |
238 | * @param pCache [in] cache from which object was allocated. |
239 | * @param pObj [in] object to free. |
240 | * |
241 | * @return None. |
242 | * |
243 | * @see rtl_cache_alloc() |
244 | */ |
245 | SAL_DLLPUBLIC void SAL_CALL rtl_cache_free ( |
246 | rtl_cache_type * pCache, |
247 | void * pObj |
248 | ) SAL_THROW_EXTERN_C(); |
249 | |
250 | |
251 | #ifdef __cplusplus |
252 | } |
253 | #endif |
254 | |
255 | #endif // INCLUDED_RTL_ALLOC_H |
256 | |
257 | /* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |
258 | |