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