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
29extern "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 */
41SAL_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 */
60SAL_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 */
70SAL_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 */
83SAL_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 */
93SAL_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 */
101typedef 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 */
120SAL_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 */
138SAL_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 */
152SAL_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 */
168SAL_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 */
177typedef 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 */
199SAL_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 */
220SAL_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 */
231SAL_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 */
245SAL_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