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