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  Bytes [in] memory size.
  39     @return pointer to 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  Ptr   [in] pointer to previously allocated memory.
  57     @param  Bytes [in] new memory size.
  58     @return pointer to 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  Ptr   [in] pointer to 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
  75 /** Allocate and zero memory.
  76
  77     A call to this function will return NULL upon the requested
  78     memory size being either zero or larger than currently allocatable.
  79
  80     @param  Bytes [in] memory size.
  81     @return pointer to allocated and zero'ed memory.
  82  */
  83 SAL_DLLPUBLIC void * SAL_CALL rtl_allocateZeroMemory (
  84     sal_Size Bytes
  85 ) SAL_THROW_EXTERN_C();
  86
  87
  88 /** Zero and free memory.
  89     @param  Ptr   [in] pointer to previously allocated memory.
  90     @param  Bytes [in] memory size.
  91     @return none. Memory is zero'ed and released. Ptr is invalid.
  92  */
  93 SAL_DLLPUBLIC void SAL_CALL rtl_freeZeroMemory (
  94     void *   Ptr,
  95     sal_Size Bytes
  96 ) SAL_THROW_EXTERN_C();
  97
  98
  99 /** Allocate aligned memory.
 100
 101     A call to this function will return NULL upon the requested
 102     memory size being either zero or larger than currently allocatable.
 103
 104     Memory obtained through this function must be freed with
 105     rtl_freeAlignedMemory.
 106
 107     @param Alignment [in] alignment in bytes, must be a power of two multiple of
 108         sizeof(void*).
 109     @param  Bytes [in] memory size.
 110     @return pointer to allocated memory.
 111
 112     @since LibreOffice 4.3
 113  */
 114 SAL_DLLPUBLIC void* SAL_CALL rtl_allocateAlignedMemory (
 115     sal_Size Alignment,
 116     sal_Size Bytes
 117 ) SAL_THROW_EXTERN_C();
 118
 119
 120 /** Free memory allocated with rtl_allocateAlignedMemory.
 121
 122     @param  Ptr   [in] pointer to previously allocated memory.
 123     @return none. Memory is released. Ptr is invalid.
 124
 125     @since LibreOffice 4.3
 126  */
 127 SAL_DLLPUBLIC void SAL_CALL rtl_freeAlignedMemory (
 128     void *   Ptr
 129 ) SAL_THROW_EXTERN_C();
 130
 131
 132 /** Opaque rtl_arena_type.
 133  */
 134 typedef struct rtl_arena_st rtl_arena_type;
 135
 136 #define RTL_ARENA_NAME_LENGTH 31
 137
 138
 139 /** rtl_arena_create()
 140  *
 141  *  @param  pName             [in] descriptive name; for debugging purposes.
 142  *  @param  quantum           [in] resource allocation unit / granularity; rounded up to next power of 2.
 143  *  @param  quantum_cache_max [in] max resources to cache; rounded up to next multiple of quantum; usually 0.
 144  *  @param  source_arena      [in] passed as argument to source_alloc, source_free; usually NULL.
 145  *  @param  source_alloc      [in] function to allocate resources; usually rtl_arena_alloc.
 146  *  @param  source_free       [in] function to free resources; usually rtl_arena_free.
 147  *  @param  nFlags            [in] flags; usually 0.
 148  *
 149  *  @return pointer to rtl_arena_type, or NULL upon failure.
 150  *
 151  *  @see rtl_arena_destroy()
 152  */
 153 SAL_DLLPUBLIC rtl_arena_type * SAL_CALL rtl_arena_create (
 154     const char *       pName,
 155     sal_Size           quantum,
 156     sal_Size           quantum_cache_max,
 157     rtl_arena_type *   source_arena,
 158     void * (SAL_CALL * source_alloc)(rtl_arena_type *, sal_Size *),
 159     void   (SAL_CALL * source_free) (rtl_arena_type *, void *, sal_Size),
 160     int                nFlags
 161 ) SAL_THROW_EXTERN_C();
 162
 163
 164 /** rtl_arena_destroy()
 165  *
 166  *  @param  pArena [in] the arena to destroy.
 167  *  @return None
 168  *
 169  *  @see rtl_arena_create()
 170  */
 171 SAL_DLLPUBLIC void SAL_CALL rtl_arena_destroy (
 172     rtl_arena_type * pArena
 173 ) SAL_THROW_EXTERN_C();
 174
 175
 176 /** rtl_arena_alloc()
 177  *
 178  *  @param  pArena [in]    arena from which resource is allocated.
 179  *  @param  pBytes [inout] size of resource to allocate.
 180  *
 181  *  @return allocated resource, or NULL upon failure.
 182  *
 183  *  @see rtl_arena_free()
 184  */
 185 SAL_DLLPUBLIC void * SAL_CALL rtl_arena_alloc (
 186     rtl_arena_type * pArena,
 187     sal_Size *       pBytes
 188 ) SAL_THROW_EXTERN_C();
 189
 190
 191 /** rtl_arena_free()
 192  *
 193  *  @param  pArena [in] arena from which resource was allocated.
 194  *  @param  pAddr  [in] resource to free.
 195  *  @param  nBytes [in] size of resource.
 196  *
 197  *  @return None.
 198  *
 199  *  @see rtl_arena_alloc()
 200  */
 201 SAL_DLLPUBLIC void SAL_CALL rtl_arena_free (
 202     rtl_arena_type * pArena,
 203     void *           pAddr,
 204     sal_Size         nBytes
 205 ) SAL_THROW_EXTERN_C();
 206
 207
 208 /** Opaque rtl_cache_type.
 209  */
 210 typedef struct rtl_cache_st rtl_cache_type;
 211
 212 #define RTL_CACHE_NAME_LENGTH 31
 213
 214 #define RTL_CACHE_FLAG_BULKDESTROY 1
 215
 216 /** rtl_cache_create()
 217  *
 218  *  @param  pName       [in] descriptive name; for debugging purposes.
 219  *  @param  nObjSize    [in] object size.
 220  *  @param  nObjAlign   [in] object alignment; usually 0 for suitable default.
 221  *  @param  constructor [in] object constructor callback function; returning 1 for success or 0 for failure.
 222  *  @param  destructor  [in] object destructor callback function.
 223  *  @param  reclaim     [in] reclaim callback function.
 224  *  @param  pUserArg    [in] opaque argument passed to callback functions.
 225  *  @param  pSource     [in] opaque argument passed to callback functions.
 226  *  @param  nFlags      [in] flags.
 227  *
 228  *  @return pointer to rtl_cache_type, or NULL upon failure.
 229  *
 230  *  @see rtl_cache_destroy()
 231  */
 232 SAL_DLLPUBLIC rtl_cache_type * SAL_CALL rtl_cache_create (
 233     const char *     pName,
 234     sal_Size         nObjSize,
 235     sal_Size         nObjAlign,
 236     int  (SAL_CALL * constructor)(void * pObj, void * pUserArg),
 237     void (SAL_CALL * destructor) (void * pObj, void * pUserArg),
 238     void (SAL_CALL * reclaim)    (void * pUserArg),
 239     void *           pUserArg,
 240     rtl_arena_type * pSource,
 241     int              nFlags
 242 ) SAL_THROW_EXTERN_C();
 243
 244
 245 /** rtl_cache_destroy()
 246  *
 247  *  @param  pCache [in] the cache to destroy.
 248  *
 249  *  @return None.
 250  *
 251  *  @see rtl_cache_create()
 252  */
 253 SAL_DLLPUBLIC void SAL_CALL rtl_cache_destroy (
 254     rtl_cache_type * pCache
 255 ) SAL_THROW_EXTERN_C();
 256
 257
 258 /** rtl_cache_alloc()
 259  *
 260  *  @param  pCache [in] cache from which object is allocated.
 261  *
 262  *  @return pointer to allocated object, or NULL upon failure.
 263  */
 264 SAL_DLLPUBLIC void * SAL_CALL rtl_cache_alloc (
 265     rtl_cache_type * pCache
 266 ) SAL_THROW_EXTERN_C();
 267
 268
 269 /** rtl_cache_free()
 270  *
 271  *  @param  pCache [in] cache from which object was allocated.
 272  *  @param  pObj   [in] object to free.
 273  *
 274  *  @return None.
 275  *
 276  *  @see rtl_cache_alloc()
 277  */
 278 SAL_DLLPUBLIC void SAL_CALL rtl_cache_free (
 279     rtl_cache_type * pCache,
 280     void *           pObj
 281 ) SAL_THROW_EXTERN_C();
 282
 283
 284 #ifdef __cplusplus
 285 }
 286 #endif
 287
 288 #endif // INCLUDED_RTL_ALLOC_H
 289
 290 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */