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 /** Opaque rtl_arena_type.
 100  */
 101 typedef struct rtl_arena_st rtl_arena_type;
 102
 103 #define RTL_ARENA_NAME_LENGTH 31
 104
 105
 106 /** rtl_arena_create()
 107  *
 108  *  @param  pName             [in] descriptive name; for debugging purposes.
 109  *  @param  quantum           [in] resource allocation unit / granularity; rounded up to next power of 2.
 110  *  @param  quantum_cache_max [in] max resources to cache; rounded up to next multiple of quantum; usually 0.
 111  *  @param  source_arena      [in] passed as argument to source_alloc, source_free; usually NULL.
 112  *  @param  source_alloc      [in] function to allocate resources; usually rtl_arena_alloc.
 113  *  @param  source_free       [in] function to free resources; usually rtl_arena_free.
 114  *  @param  nFlags            [in] flags; usually 0.
 115  *
 116  *  @return pointer to rtl_arena_type, or NULL upon failure.
 117  *
 118  *  @see rtl_arena_destroy()
 119  */
 120 SAL_DLLPUBLIC rtl_arena_type * SAL_CALL rtl_arena_create (
 121     const char *       pName,
 122     sal_Size           quantum,
 123     sal_Size           quantum_cache_max,
 124     rtl_arena_type *   source_arena,
 125     void * (SAL_CALL * source_alloc)(rtl_arena_type *, sal_Size *),
 126     void   (SAL_CALL * source_free) (rtl_arena_type *, void *, sal_Size),
 127     int                nFlags
 128 ) SAL_THROW_EXTERN_C();
 129
 130
 131 /** rtl_arena_destroy()
 132  *
 133  *  @param  pArena [in] the arena to destroy.
 134  *  @return None
 135  *
 136  *  @see rtl_arena_create()
 137  */
 138 SAL_DLLPUBLIC void SAL_CALL rtl_arena_destroy (
 139     rtl_arena_type * pArena
 140 ) SAL_THROW_EXTERN_C();
 141
 142
 143 /** rtl_arena_alloc()
 144  *
 145  *  @param  pArena [in]    arena from which resource is allocated.
 146  *  @param  pBytes [inout] size of resource to allocate.
 147  *
 148  *  @return allocated resource, or NULL upon failure.
 149  *
 150  *  @see rtl_arena_free()
 151  */
 152 SAL_DLLPUBLIC void * SAL_CALL rtl_arena_alloc (
 153     rtl_arena_type * pArena,
 154     sal_Size *       pBytes
 155 ) SAL_THROW_EXTERN_C();
 156
 157
 158 /** rtl_arena_free()
 159  *
 160  *  @param  pArena [in] arena from which resource was allocated.
 161  *  @param  pAddr  [in] resource to free.
 162  *  @param  nBytes [in] size of resource.
 163  *
 164  *  @return None.
 165  *
 166  *  @see rtl_arena_alloc()
 167  */
 168 SAL_DLLPUBLIC void SAL_CALL rtl_arena_free (
 169     rtl_arena_type * pArena,
 170     void *           pAddr,
 171     sal_Size         nBytes
 172 ) SAL_THROW_EXTERN_C();
 173
 174
 175 /** Opaque rtl_cache_type.
 176  */
 177 typedef struct rtl_cache_st rtl_cache_type;
 178
 179 #define RTL_CACHE_NAME_LENGTH 31
 180
 181 #define RTL_CACHE_FLAG_BULKDESTROY 1
 182
 183 /** rtl_cache_create()
 184  *
 185  *  @param  pName       [in] descriptive name; for debugging purposes.
 186  *  @param  nObjSize    [in] object size.
 187  *  @param  nObjAlign   [in] object alignment; usually 0 for suitable default.
 188  *  @param  constructor [in] object constructor callback function; returning 1 for success or 0 for failure.
 189  *  @param  destructor  [in] object destructor callback function.
 190  *  @param  reclaim     [in] reclaim callback function.
 191  *  @param  pUserArg    [in] opaque argument passed to callback functions.
 192  *  @param  pSource     [in] opaque argument passed to callback functions.
 193  *  @param  nFlags      [in] flags.
 194  *
 195  *  @return pointer to rtl_cache_type, or NULL upon failure.
 196  *
 197  *  @see rtl_cache_destroy()
 198  */
 199 SAL_DLLPUBLIC rtl_cache_type * SAL_CALL rtl_cache_create (
 200     const char *     pName,
 201     sal_Size         nObjSize,
 202     sal_Size         nObjAlign,
 203     int  (SAL_CALL * constructor)(void * pObj, void * pUserArg),
 204     void (SAL_CALL * destructor) (void * pObj, void * pUserArg),
 205     void (SAL_CALL * reclaim)    (void * pUserArg),
 206     void *           pUserArg,
 207     rtl_arena_type * pSource,
 208     int              nFlags
 209 ) SAL_THROW_EXTERN_C();
 210
 211
 212 /** rtl_cache_destroy()
 213  *
 214  *  @param  pCache [in] the cache to destroy.
 215  *
 216  *  @return None.
 217  *
 218  *  @see rtl_cache_create()
 219  */
 220 SAL_DLLPUBLIC void SAL_CALL rtl_cache_destroy (
 221     rtl_cache_type * pCache
 222 ) SAL_THROW_EXTERN_C();
 223
 224
 225 /** rtl_cache_alloc()
 226  *
 227  *  @param  pCache [in] cache from which object is allocated.
 228  *
 229  *  @return pointer to allocated object, or NULL upon failure.
 230  */
 231 SAL_DLLPUBLIC void * SAL_CALL rtl_cache_alloc (
 232     rtl_cache_type * pCache
 233 ) SAL_THROW_EXTERN_C();
 234
 235
 236 /** rtl_cache_free()
 237  *
 238  *  @param  pCache [in] cache from which object was allocated.
 239  *  @param  pObj   [in] object to free.
 240  *
 241  *  @return None.
 242  *
 243  *  @see rtl_cache_alloc()
 244  */
 245 SAL_DLLPUBLIC void SAL_CALL rtl_cache_free (
 246     rtl_cache_type * pCache,
 247     void *           pObj
 248 ) SAL_THROW_EXTERN_C();
 249
 250
 251 #ifdef __cplusplus
 252 }
 253 #endif
 254
 255 #endif // INCLUDED_RTL_ALLOC_H
 256
 257 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */