1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
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"
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 (
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()
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 (
67 ) SAL_THROW_EXTERN_C();
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 (
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 (
90 ) SAL_THROW_EXTERN_C();
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 (
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 (
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
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 (
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 (
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 (
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
),
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
,
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
,
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 (
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
),
255 rtl_arena_type
* pSource
,
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
,
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
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
320 * @since LibreOffice 6.1
322 SAL_DLLPUBLIC
void SAL_CALL
rtl_alloc_preInit (
324 ) SAL_THROW_EXTERN_C();
333 #endif // INCLUDED_RTL_ALLOC_H
335 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */