Version 24.8.3.2, tag libreoffice-24.8.3.2
[LibreOffice.git] / include / rtl / alloc.h
blob1dc9cefacb0da31a981ab4832884031ee25422cd
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * This file is part of the LibreOffice project.
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/.
9 * This file incorporates work covered by the following license notice:
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 .
21 * This file is part of LibreOffice published API.
24 #ifndef INCLUDED_RTL_ALLOC_H
25 #define INCLUDED_RTL_ALLOC_H
27 #include "sal/config.h"
29 #include "sal/saldllapi.h"
30 #include "sal/types.h"
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
37 /** Allocate memory.
39 A call to this function will return NULL upon the requested
40 memory size being either zero or larger than currently allocatable.
42 @param[in] Bytes memory size.
43 @return pointer to the allocated memory.
45 SAL_DLLPUBLIC void * SAL_CALL rtl_allocateMemory (
46 sal_Size Bytes
47 ) SAL_THROW_EXTERN_C();
50 /** Reallocate memory.
52 A call to this function with parameter 'Ptr' being NULL
53 is equivalent to a rtl_allocateMemory() call.
54 A call to this function with parameter 'Bytes' being 0
55 is equivalent to a rtl_freeMemory() call.
57 @see rtl_allocateMemory()
58 @see rtl_freeMemory()
60 @param[in] Ptr pointer to the previously allocated memory.
61 @param[in] Bytes new memory size.
62 @return pointer to the reallocated memory. May differ from Ptr.
64 SAL_DLLPUBLIC void * SAL_CALL rtl_reallocateMemory (
65 void * Ptr,
66 sal_Size Bytes
67 ) SAL_THROW_EXTERN_C();
70 /** Free memory.
72 Memory is released, and the pointer is invalidated.
74 @param[in] Ptr pointer to the previously allocated memory.
76 SAL_DLLPUBLIC void SAL_CALL rtl_freeMemory (
77 void * Ptr
78 ) SAL_THROW_EXTERN_C();
80 /** Allocate and zero memory.
82 A call to this function will return NULL upon the requested
83 memory size being either zero or larger than currently allocatable.
85 @param[in] Bytes memory size.
86 @return pointer to the allocated and zero'ed memory.
88 SAL_DLLPUBLIC void * SAL_CALL rtl_allocateZeroMemory (
89 sal_Size Bytes
90 ) SAL_THROW_EXTERN_C();
92 /** Zero memory
94 Fills a block of memory with zeros in a way that is guaranteed to be secure
96 @param[in] Ptr pointer to the previously allocated memory.
97 @param[in] Bytes memory size.
99 @since LibreOffice 5.0
101 SAL_DLLPUBLIC void SAL_CALL rtl_secureZeroMemory (
102 void * Ptr,
103 sal_Size Bytes
104 ) SAL_THROW_EXTERN_C();
107 /** Zero and free memory.
109 Memory is zero'ed with rtl_secureZeroMemory() and released.
110 The original pointer is no longer valid.
112 @param[in] Ptr pointer to the previously allocated memory.
113 @param[in] Bytes memory size.
115 SAL_DLLPUBLIC void SAL_CALL rtl_freeZeroMemory (
116 void * Ptr,
117 sal_Size Bytes
118 ) SAL_THROW_EXTERN_C();
120 /** Allocate aligned memory.
122 A call to this function will return NULL upon the requested
123 memory size being either zero or larger than currently allocatable.
125 Memory obtained through this function must be freed with
126 rtl_freeAlignedMemory().
128 @param[in] Alignment alignment in bytes, must be a power of two multiple of
129 sizeof(void*).
130 @param[in] Bytes memory size.
131 @return pointer to the allocated memory.
133 @since LibreOffice 4.3
135 SAL_DLLPUBLIC void* SAL_CALL rtl_allocateAlignedMemory (
136 sal_Size Alignment,
137 sal_Size Bytes
138 ) SAL_THROW_EXTERN_C();
141 /** Free memory allocated with rtl_allocateAlignedMemory().
143 Memory is released, and the pointer invalidated.
145 @param[in] Ptr pointer to the previously allocated memory.
147 @since LibreOffice 4.3
149 SAL_DLLPUBLIC void SAL_CALL rtl_freeAlignedMemory (
150 void * Ptr
151 ) SAL_THROW_EXTERN_C();
154 /** Opaque rtl_arena_type.
156 struct SAL_DLLPUBLIC_RTTI rtl_arena_st;
157 typedef struct rtl_arena_st rtl_arena_type;
159 #define RTL_ARENA_NAME_LENGTH 31
163 * @param[in] pName descriptive name; for debugging purposes.
164 * @param[in] quantum resource allocation unit / granularity; rounded up to next power of 2.
165 * @param[in] quantum_cache_max no longer used, should be 0.
166 * @param[in] source_arena passed as argument to source_alloc, source_free; usually NULL.
167 * @param[in] source_alloc function to allocate resources; usually rtl_arena_alloc.
168 * @param[in] source_free function to free resources; usually rtl_arena_free.
169 * @param[in] nFlags flags; usually 0.
171 * @return pointer to rtl_arena_type, or NULL upon failure.
173 * @see rtl_arena_destroy()
175 SAL_DLLPUBLIC rtl_arena_type * SAL_CALL rtl_arena_create (
176 const char * pName,
177 sal_Size quantum,
178 sal_Size quantum_cache_max,
179 rtl_arena_type * source_arena,
180 void * (SAL_CALL * source_alloc)(rtl_arena_type *, sal_Size *),
181 void (SAL_CALL * source_free) (rtl_arena_type *, void *, sal_Size),
182 int nFlags
183 ) SAL_THROW_EXTERN_C();
187 * @param[in] pArena the arena to destroy.
189 * @see rtl_arena_create()
191 SAL_DLLPUBLIC void SAL_CALL rtl_arena_destroy (
192 rtl_arena_type * pArena
193 ) SAL_THROW_EXTERN_C();
197 * @param[in] pArena arena from which resource is allocated.
198 * @param[in,out] pBytes size of resource to allocate.
200 * @return allocated resource, or NULL upon failure.
202 * @see rtl_arena_free()
204 SAL_DLLPUBLIC void * SAL_CALL rtl_arena_alloc (
205 rtl_arena_type * pArena,
206 sal_Size * pBytes
207 ) SAL_THROW_EXTERN_C();
211 * @param[in] pArena arena from which resource was allocated.
212 * @param[in] pAddr resource to free.
213 * @param[in] nBytes size of resource.
215 * @see rtl_arena_alloc()
217 SAL_DLLPUBLIC void SAL_CALL rtl_arena_free (
218 rtl_arena_type * pArena,
219 void * pAddr,
220 sal_Size nBytes
221 ) SAL_THROW_EXTERN_C();
224 /** Opaque rtl_cache_type.
226 typedef struct rtl_cache_st rtl_cache_type;
228 #define RTL_CACHE_NAME_LENGTH 31
230 #define RTL_CACHE_FLAG_BULKDESTROY 1 /* obsolete */
233 * @param[in] pName descriptive name; for debugging purposes.
234 * @param[in] nObjSize object size.
235 * @param[in] nObjAlign object alignment; usually 0 for suitable default.
236 * @param[in] constructor object constructor callback function; returning 1 for success or 0 for failure.
237 * @param[in] destructor object destructor callback function.
238 * @param[in] reclaim reclaim callback function.
239 * @param[in] pUserArg opaque argument passed to callback functions.
240 * @param[in] pSource unused argument (should be null).
241 * @param[in] nFlags flags (unused).
243 * @return pointer to rtl_cache_type, or NULL upon failure.
245 * @see rtl_cache_destroy()
247 SAL_DLLPUBLIC rtl_cache_type * SAL_CALL rtl_cache_create (
248 const char * pName,
249 sal_Size nObjSize,
250 sal_Size nObjAlign,
251 int (SAL_CALL * constructor)(void * pObj, void * pUserArg),
252 void (SAL_CALL * destructor) (void * pObj, void * pUserArg),
253 void (SAL_CALL * reclaim) (void * pUserArg),
254 void * pUserArg,
255 rtl_arena_type * pSource,
256 int nFlags
257 ) SAL_THROW_EXTERN_C();
261 * @param[in] pCache the cache to destroy.
263 * @see rtl_cache_create()
265 SAL_DLLPUBLIC void SAL_CALL rtl_cache_destroy (
266 rtl_cache_type * pCache
267 ) SAL_THROW_EXTERN_C();
271 * @param[in] pCache cache from which object is allocated.
273 * @return pointer to the allocated object, or NULL upon failure.
275 SAL_DLLPUBLIC void * SAL_CALL rtl_cache_alloc (
276 rtl_cache_type * pCache
277 ) SAL_THROW_EXTERN_C();
281 * @param[in] pCache cache from which object was allocated.
282 * @param[in] pObj object to free.
284 * @see rtl_cache_alloc()
286 SAL_DLLPUBLIC void SAL_CALL rtl_cache_free (
287 rtl_cache_type * pCache,
288 void * pObj
289 ) SAL_THROW_EXTERN_C();
292 #ifdef LIBO_INTERNAL_ONLY
294 /** @cond INTERNAL */
295 /** rtl_alloc_preInit
297 * This function, is called at the beginning and again
298 * at the end of LibreOfficeKit pre-initialization to enable
299 * various optimizations.
301 * Its function is to annotate a section @start = true
302 * to end (@start = false) via. two calls. Inside this
303 * section string allocators are replaced with ones which cause the
304 * strings to be staticized at the end of the section.
306 * This brings a number of constraints - in particular no
307 * string allocated outside the section should be freed
308 * inside it, practically this means starting the section
309 * as early as possible. No string allocated inside the
310 * section will be freed subsequently as they are
311 * staticized.
313 * This method is not thread-safe, nor intended for use in
314 * a threaded context, cf. previous constraints.
316 * It is almost certainly not the method that you want,
317 * use with extraordinary care referring to the
318 * implementation.
320 * @since LibreOffice 6.1
322 SAL_DLLPUBLIC void SAL_CALL rtl_alloc_preInit (
323 sal_Bool start
324 ) SAL_THROW_EXTERN_C();
325 /** @endcond */
327 #endif
329 #ifdef __cplusplus
331 #endif
333 #endif // INCLUDED_RTL_ALLOC_H
335 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */