include/rtl/alloc.h

   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 /*
  21  * This file is part of LibreOffice published API.
  22  */
  23
  24 #ifndef INCLUDED_RTL_ALLOC_H
  25 #define INCLUDED_RTL_ALLOC_H
  26
  27 #include "sal/config.h"
  28
  29 #include "sal/saldllapi.h"
  30 #include "sal/types.h"
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36
  37 /** Allocate memory.
  38
  39     A call to this function will return NULL upon the requested
  40     memory size being either zero or larger than currently allocatable.
  41
  42     @param[in] Bytes memory size.
  43     @return pointer to the allocated memory.
  44  */
  45 SAL_DLLPUBLIC void * SAL_CALL rtl_allocateMemory (
  46     sal_Size Bytes
  47 ) SAL_THROW_EXTERN_C();
  48
  49
  50 /** Reallocate memory.
  51
  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.
  56
  57     @see rtl_allocateMemory()
  58     @see rtl_freeMemory()
  59
  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.
  63  */
  64 SAL_DLLPUBLIC void * SAL_CALL rtl_reallocateMemory (
  65     void *   Ptr,
  66     sal_Size Bytes
  67 ) SAL_THROW_EXTERN_C();
  68
  69
  70 /** Free memory.
  71     @param[in] Ptr pointer to the previously allocated memory.
  72     @return none. Memory is released. Ptr is invalid.
  73  */
  74 SAL_DLLPUBLIC void SAL_CALL rtl_freeMemory (
  75     void * Ptr
  76 ) SAL_THROW_EXTERN_C();
  77
  78 /** Allocate and zero memory.
  79
  80     A call to this function will return NULL upon the requested
  81     memory size being either zero or larger than currently allocatable.
  82
  83     @param[in] Bytes memory size.
  84     @return pointer to the allocated and zero'ed memory.
  85  */
  86 SAL_DLLPUBLIC void * SAL_CALL rtl_allocateZeroMemory (
  87     sal_Size Bytes
  88 ) SAL_THROW_EXTERN_C();
  89
  90 /** Zero memory
  91
  92     Fills a block of memory with zeros in a way that is guaranteed to be secure
  93
  94     @param[in] Ptr   pointer to the previously allocated memory.
  95     @param[in] Bytes memory size.
  96
  97     @since LibreOffice 5.0
  98  */
  99 SAL_DLLPUBLIC void SAL_CALL rtl_secureZeroMemory (
 100     void *   Ptr,
 101     sal_Size Bytes
 102 ) SAL_THROW_EXTERN_C();
 103
 104
 105 /** Zero and free memory.
 106     @param[in] Ptr   pointer to the previously allocated memory.
 107     @param[in] Bytes memory size.
 108     @return none. Memory is zero'ed with rtl_secureZeroMemory() and released.
 109                   Ptr is invalid.
 110  */
 111 SAL_DLLPUBLIC void SAL_CALL rtl_freeZeroMemory (
 112     void *   Ptr,
 113     sal_Size Bytes
 114 ) SAL_THROW_EXTERN_C();
 115
 116 /** Allocate aligned memory.
 117
 118     A call to this function will return NULL upon the requested
 119     memory size being either zero or larger than currently allocatable.
 120
 121     Memory obtained through this function must be freed with
 122     rtl_freeAlignedMemory().
 123
 124     @param[in] Alignment alignment in bytes, must be a power of two multiple of
 125         sizeof(void*).
 126     @param[in] Bytes     memory size.
 127     @return pointer to the allocated memory.
 128
 129     @since LibreOffice 4.3
 130  */
 131 SAL_DLLPUBLIC void* SAL_CALL rtl_allocateAlignedMemory (
 132     sal_Size Alignment,
 133     sal_Size Bytes
 134 ) SAL_THROW_EXTERN_C();
 135
 136
 137 /** Free memory allocated with rtl_allocateAlignedMemory().
 138
 139     @param[in] Ptr pointer to the previously allocated memory.
 140     @return none. Memory is released. Ptr is invalid.
 141
 142     @since LibreOffice 4.3
 143  */
 144 SAL_DLLPUBLIC void SAL_CALL rtl_freeAlignedMemory (
 145     void *   Ptr
 146 ) SAL_THROW_EXTERN_C();
 147
 148
 149 /** Opaque rtl_arena_type.
 150  */
 151 typedef struct SAL_DLLPUBLIC_RTTI rtl_arena_st rtl_arena_type;
 152
 153 #define RTL_ARENA_NAME_LENGTH 31
 154
 155
 156 /**
 157  *  @param[in] pName             descriptive name; for debugging purposes.
 158  *  @param[in] quantum           resource allocation unit / granularity; rounded up to next power of 2.
 159  *  @param[in] quantum_cache_max no longer used, should be 0.
 160  *  @param[in] source_arena      passed as argument to source_alloc, source_free; usually NULL.
 161  *  @param[in] source_alloc      function to allocate resources; usually rtl_arena_alloc.
 162  *  @param[in] source_free       function to free resources; usually rtl_arena_free.
 163  *  @param[in] nFlags            flags; usually 0.
 164  *
 165  *  @return pointer to rtl_arena_type, or NULL upon failure.
 166  *
 167  *  @see rtl_arena_destroy()
 168  */
 169 SAL_DLLPUBLIC rtl_arena_type * SAL_CALL rtl_arena_create (
 170     const char *       pName,
 171     sal_Size           quantum,
 172     sal_Size           quantum_cache_max,
 173     rtl_arena_type *   source_arena,
 174     void * (SAL_CALL * source_alloc)(rtl_arena_type *, sal_Size *),
 175     void   (SAL_CALL * source_free) (rtl_arena_type *, void *, sal_Size),
 176     int                nFlags
 177 ) SAL_THROW_EXTERN_C();
 178
 179
 180 /**
 181  *  @param[in] pArena the arena to destroy.
 182  *  @return None
 183  *
 184  *  @see rtl_arena_create()
 185  */
 186 SAL_DLLPUBLIC void SAL_CALL rtl_arena_destroy (
 187     rtl_arena_type * pArena
 188 ) SAL_THROW_EXTERN_C();
 189
 190
 191 /**
 192  *  @param[in]     pArena arena from which resource is allocated.
 193  *  @param[in,out] pBytes size of resource to allocate.
 194  *
 195  *  @return allocated resource, or NULL upon failure.
 196  *
 197  *  @see rtl_arena_free()
 198  */
 199 SAL_DLLPUBLIC void * SAL_CALL rtl_arena_alloc (
 200     rtl_arena_type * pArena,
 201     sal_Size *       pBytes
 202 ) SAL_THROW_EXTERN_C();
 203
 204
 205 /**
 206  *  @param[in] pArena arena from which resource was allocated.
 207  *  @param[in] pAddr  resource to free.
 208  *  @param[in] nBytes size of resource.
 209  *
 210  *  @return None.
 211  *
 212  *  @see rtl_arena_alloc()
 213  */
 214 SAL_DLLPUBLIC void SAL_CALL rtl_arena_free (
 215     rtl_arena_type * pArena,
 216     void *           pAddr,
 217     sal_Size         nBytes
 218 ) SAL_THROW_EXTERN_C();
 219
 220
 221 /** Opaque rtl_cache_type.
 222  */
 223 typedef struct rtl_cache_st rtl_cache_type;
 224
 225 #define RTL_CACHE_NAME_LENGTH 31
 226
 227 #define RTL_CACHE_FLAG_BULKDESTROY 1 /* obsolete */
 228
 229 /**
 230  *  @param[in] pName       descriptive name; for debugging purposes.
 231  *  @param[in] nObjSize    object size.
 232  *  @param[in] nObjAlign   object alignment; usually 0 for suitable default.
 233  *  @param[in] constructor object constructor callback function; returning 1 for success or 0 for failure.
 234  *  @param[in] destructor  object destructor callback function.
 235  *  @param[in] reclaim     reclaim callback function.
 236  *  @param[in] pUserArg    opaque argument passed to callback functions.
 237  *  @param[in] pSource     unused argument (should be null).
 238  *  @param[in] nFlags      flags (unused).
 239  *
 240  *  @return pointer to rtl_cache_type, or NULL upon failure.
 241  *
 242  *  @see rtl_cache_destroy()
 243  */
 244 SAL_DLLPUBLIC rtl_cache_type * SAL_CALL rtl_cache_create (
 245     const char *     pName,
 246     sal_Size         nObjSize,
 247     sal_Size         nObjAlign,
 248     int  (SAL_CALL * constructor)(void * pObj, void * pUserArg),
 249     void (SAL_CALL * destructor) (void * pObj, void * pUserArg),
 250     void (SAL_CALL * reclaim)    (void * pUserArg),
 251     void *           pUserArg,
 252     rtl_arena_type * pSource,
 253     int              nFlags
 254 ) SAL_THROW_EXTERN_C();
 255
 256
 257 /**
 258  *  @param[in] pCache the cache to destroy.
 259  *
 260  *  @return None.
 261  *
 262  *  @see rtl_cache_create()
 263  */
 264 SAL_DLLPUBLIC void SAL_CALL rtl_cache_destroy (
 265     rtl_cache_type * pCache
 266 ) SAL_THROW_EXTERN_C();
 267
 268
 269 /**
 270  *  @param[in] pCache cache from which object is allocated.
 271  *
 272  *  @return pointer to the allocated object, or NULL upon failure.
 273  */
 274 SAL_DLLPUBLIC void * SAL_CALL rtl_cache_alloc (
 275     rtl_cache_type * pCache
 276 ) SAL_THROW_EXTERN_C();
 277
 278
 279 /**
 280  *  @param[in] pCache cache from which object was allocated.
 281  *  @param[in] pObj   object to free.
 282  *
 283  *  @return None.
 284  *
 285  *  @see rtl_cache_alloc()
 286  */
 287 SAL_DLLPUBLIC void SAL_CALL rtl_cache_free (
 288     rtl_cache_type * pCache,
 289     void *           pObj
 290 ) SAL_THROW_EXTERN_C();
 291
 292
 293 #ifdef LIBO_INTERNAL_ONLY
 294
 295 /** @cond INTERNAL */
 296 /** rtl_alloc_preInit
 297  *
 298  * This function, is called at the beginning and again
 299  * at the end of LibreOfficeKit pre-initialization to enable
 300  * various optimizations.
 301  *
 302  * Its function is to annotate a section @start = true
 303  * to end (@start = false) via. two calls. Inside this
 304  * section string allocators are replaced with ones which cause the
 305  * strings to be staticized at the end of the section.
 306  *
 307  * This brings a number of constraints - in particular no
 308  * string allocated outside the section should be freed
 309  * inside it, practically this means starting the section
 310  * as early as possible. No string allocated inside the
 311  * section will be freed subsequently as they are
 312  * staticized.
 313  *
 314  * This method is not thread-safe, nor intended for use in
 315  * a threaded context, cf. previous constraints.
 316  *
 317  * It is almost certainly not the method that you want,
 318  * use with extraordinary care referring to the
 319  * implementation.
 320  *
 321  * @since LibreOffice 6.1
 322  */
 323 SAL_DLLPUBLIC void SAL_CALL rtl_alloc_preInit (
 324     sal_Bool start
 325 ) SAL_THROW_EXTERN_C();
 326 /** @endcond */
 327
 328 #endif
 329
 330 #ifdef __cplusplus
 331 }
 332 #endif
 333
 334 #endif // INCLUDED_RTL_ALLOC_H
 335
 336 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */