include/apr_rmm.h

   1 /* Licensed to the Apache Software Foundation (ASF) under one or more
   2  * contributor license agreements.  See the NOTICE file distributed with
   3  * this work for additional information regarding copyright ownership.
   4  * The ASF licenses this file to You under the Apache License, Version 2.0
   5  * (the "License"); you may not use this file except in compliance with
   6  * the License.  You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef APR_RMM_H
  18 #define APR_RMM_H
  19 /**
  20  * @file apr_rmm.h
  21  * @brief APR-UTIL Relocatable Memory Management Routines
  22  */
  23 /**
  24  * @defgroup APR_Util_RMM Relocatable Memory Management Routines
  25  * @ingroup APR_Util
  26  * @{
  27  */
  28
  29 #include "apr.h"
  30 #include "apr_pools.h"
  31 #include "apr_errno.h"
  32 #include "apu.h"
  33 #include "apr_anylock.h"
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif /* __cplusplus */
  38
  39 /** Structure to access Relocatable, Managed Memory */
  40 typedef struct apr_rmm_t apr_rmm_t;
  41
  42 /** Fundamental allocation unit, within a specific apr_rmm_t */
  43 typedef apr_size_t   apr_rmm_off_t;
  44
  45 /**
  46  * Initialize a relocatable memory block to be managed by the apr_rmm API.
  47  * @param rmm The relocatable memory block
  48  * @param lock An apr_anylock_t of the appropriate type of lock, or NULL
  49  *             if no locking is required.
  50  * @param membuf The block of relocatable memory to be managed
  51  * @param memsize The size of relocatable memory block to be managed
  52  * @param cont The pool to use for local storage and management
  53  * @remark Both @param membuf and @param memsize must be aligned
  54  * (for instance using APR_ALIGN_DEFAULT).
  55  */
  56 APU_DECLARE(apr_status_t) apr_rmm_init(apr_rmm_t **rmm, apr_anylock_t *lock,
  57                                        void *membuf, apr_size_t memsize,
  58                                        apr_pool_t *cont);
  59
  60 /**
  61  * Destroy a managed memory block.
  62  * @param rmm The relocatable memory block to destroy
  63  */
  64 APU_DECLARE(apr_status_t) apr_rmm_destroy(apr_rmm_t *rmm);
  65
  66 /**
  67  * Attach to a relocatable memory block already managed by the apr_rmm API.
  68  * @param rmm The relocatable memory block
  69  * @param lock An apr_anylock_t of the appropriate type of lock
  70  * @param membuf The block of relocatable memory already under management
  71  * @param cont The pool to use for local storage and management
  72  */
  73 APU_DECLARE(apr_status_t) apr_rmm_attach(apr_rmm_t **rmm, apr_anylock_t *lock,
  74                                          void *membuf, apr_pool_t *cont);
  75
  76 /**
  77  * Detach from the managed block of memory.
  78  * @param rmm The relocatable memory block to detach from
  79  */
  80 APU_DECLARE(apr_status_t) apr_rmm_detach(apr_rmm_t *rmm);
  81
  82 /**
  83  * Allocate memory from the block of relocatable memory.
  84  * @param rmm The relocatable memory block
  85  * @param reqsize How much memory to allocate
  86  */
  87 APU_DECLARE(apr_rmm_off_t) apr_rmm_malloc(apr_rmm_t *rmm, apr_size_t reqsize);
  88
  89 /**
  90  * Realloc memory from the block of relocatable memory.
  91  * @param rmm The relocatable memory block
  92  * @param entity The memory allocation to realloc
  93  * @param reqsize The new size
  94  */
  95 APU_DECLARE(apr_rmm_off_t) apr_rmm_realloc(apr_rmm_t *rmm, void *entity, apr_size_t reqsize);
  96
  97 /**
  98  * Allocate memory from the block of relocatable memory and initialize it to zero.
  99  * @param rmm The relocatable memory block
 100  * @param reqsize How much memory to allocate
 101  */
 102 APU_DECLARE(apr_rmm_off_t) apr_rmm_calloc(apr_rmm_t *rmm, apr_size_t reqsize);
 103
 104 /**
 105  * Free allocation returned by apr_rmm_malloc or apr_rmm_calloc.
 106  * @param rmm The relocatable memory block
 107  * @param entity The memory allocation to free
 108  */
 109 APU_DECLARE(apr_status_t) apr_rmm_free(apr_rmm_t *rmm, apr_rmm_off_t entity);
 110
 111 /**
 112  * Retrieve the physical address of a relocatable allocation of memory
 113  * @param rmm The relocatable memory block
 114  * @param entity The memory allocation to free
 115  * @return address The address, aligned with APR_ALIGN_DEFAULT.
 116  */
 117 APU_DECLARE(void *) apr_rmm_addr_get(apr_rmm_t *rmm, apr_rmm_off_t entity);
 118
 119 /**
 120  * Compute the offset of a relocatable allocation of memory
 121  * @param rmm The relocatable memory block
 122  * @param entity The physical address to convert to an offset
 123  */
 124 APU_DECLARE(apr_rmm_off_t) apr_rmm_offset_get(apr_rmm_t *rmm, void *entity);
 125
 126 /**
 127  * Compute the required overallocation of memory needed to fit n allocs
 128  * @param n The number of alloc/calloc regions desired
 129  */
 130 APU_DECLARE(apr_size_t) apr_rmm_overhead_get(int n);
 131
 132 #ifdef __cplusplus
 133 }
 134 #endif
 135 /** @} */
 136 #endif  /* ! APR_RMM_H */
 137