github.com/krum110487/go-htaccess@v0.0.0-20240316004156-60641c8e7598/tests/data/apache_2_4_58/include/apr_allocator.h (about)

     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_ALLOCATOR_H
    18  #define APR_ALLOCATOR_H
    19  
    20  /**
    21   * @file apr_allocator.h
    22   * @brief APR Internal Memory Allocation
    23   */
    24  
    25  #include "apr.h"
    26  #include "apr_errno.h"
    27  #define APR_WANT_MEMFUNC /**< For no good reason? */
    28  #include "apr_want.h"
    29  
    30  #ifdef __cplusplus
    31  extern "C" {
    32  #endif
    33  
    34  /**
    35   * @defgroup apr_allocator Internal Memory Allocation
    36   * @ingroup APR 
    37   * @{
    38   */
    39  
    40  /** the allocator structure */
    41  typedef struct apr_allocator_t apr_allocator_t;
    42  /** the structure which holds information about the allocation */
    43  typedef struct apr_memnode_t apr_memnode_t;
    44  
    45  /** basic memory node structure
    46   * @note The next, ref and first_avail fields are available for use by the
    47   *       caller of apr_allocator_alloc(), the remaining fields are read-only.
    48   *       The next field has to be used with caution and sensibly set when the
    49   *       memnode is passed back to apr_allocator_free().  See apr_allocator_free()
    50   *       for details.  
    51   *       The ref and first_avail fields will be properly restored by
    52   *       apr_allocator_free().
    53   */
    54  struct apr_memnode_t {
    55      apr_memnode_t *next;            /**< next memnode */
    56      apr_memnode_t **ref;            /**< reference to self */
    57      apr_uint32_t   index;           /**< size */
    58      apr_uint32_t   free_index;      /**< how much free */
    59      char          *first_avail;     /**< pointer to first free memory */
    60      char          *endp;            /**< pointer to end of free memory */
    61  };
    62  
    63  /** The base size of a memory node - aligned.  */
    64  #define APR_MEMNODE_T_SIZE APR_ALIGN_DEFAULT(sizeof(apr_memnode_t))
    65  
    66  /** Symbolic constants */
    67  #define APR_ALLOCATOR_MAX_FREE_UNLIMITED 0
    68  
    69  /**
    70   * Create a new allocator
    71   * @param allocator The allocator we have just created.
    72   *
    73   */
    74  APR_DECLARE(apr_status_t) apr_allocator_create(apr_allocator_t **allocator)
    75                            __attribute__((nonnull(1)));
    76  
    77  /**
    78   * Destroy an allocator
    79   * @param allocator The allocator to be destroyed
    80   * @remark Any memnodes not given back to the allocator prior to destroying
    81   *         will _not_ be free()d.
    82   */
    83  APR_DECLARE(void) apr_allocator_destroy(apr_allocator_t *allocator)
    84                    __attribute__((nonnull(1)));
    85  
    86  /**
    87   * Allocate a block of mem from the allocator
    88   * @param allocator The allocator to allocate from
    89   * @param size The size of the mem to allocate (excluding the
    90   *        memnode structure)
    91   */
    92  APR_DECLARE(apr_memnode_t *) apr_allocator_alloc(apr_allocator_t *allocator,
    93                                                   apr_size_t size)
    94                               __attribute__((nonnull(1)));
    95  
    96  /**
    97   * Free a list of blocks of mem, giving them back to the allocator.
    98   * The list is typically terminated by a memnode with its next field
    99   * set to NULL.
   100   * @param allocator The allocator to give the mem back to
   101   * @param memnode The memory node to return
   102   */
   103  APR_DECLARE(void) apr_allocator_free(apr_allocator_t *allocator,
   104                                       apr_memnode_t *memnode)
   105                    __attribute__((nonnull(1,2)));
   106   
   107  /**
   108   * Get the true size that would be allocated for the given size (including
   109   * the header and alignment).
   110   * @param allocator The allocator from which to the memory would be allocated
   111   * @param size The size to align
   112   * @return The aligned size (or zero on apr_size_t overflow)
   113   */
   114  APR_DECLARE(apr_size_t) apr_allocator_align(apr_allocator_t *allocator,
   115                                              apr_size_t size);
   116  
   117  #include "apr_pools.h"
   118  
   119  /**
   120   * Set the owner of the allocator
   121   * @param allocator The allocator to set the owner for
   122   * @param pool The pool that is to own the allocator
   123   * @remark Typically pool is the highest level pool using the allocator
   124   */
   125  /*
   126   * XXX: see if we can come up with something a bit better.  Currently
   127   * you can make a pool an owner, but if the pool doesn't use the allocator
   128   * the allocator will never be destroyed.
   129   */
   130  APR_DECLARE(void) apr_allocator_owner_set(apr_allocator_t *allocator,
   131                                            apr_pool_t *pool)
   132                    __attribute__((nonnull(1)));
   133  
   134  /**
   135   * Get the current owner of the allocator
   136   * @param allocator The allocator to get the owner from
   137   */
   138  APR_DECLARE(apr_pool_t *) apr_allocator_owner_get(apr_allocator_t *allocator)
   139                            __attribute__((nonnull(1)));
   140  
   141  /**
   142   * Set the current threshold at which the allocator should start
   143   * giving blocks back to the system.
   144   * @param allocator The allocator to set the threshold on
   145   * @param size The threshold.  0 == unlimited.
   146   */
   147  APR_DECLARE(void) apr_allocator_max_free_set(apr_allocator_t *allocator,
   148                                               apr_size_t size)
   149                    __attribute__((nonnull(1)));
   150  
   151  #include "apr_thread_mutex.h"
   152  
   153  #if APR_HAS_THREADS
   154  /**
   155   * Set a mutex for the allocator to use
   156   * @param allocator The allocator to set the mutex for
   157   * @param mutex The mutex
   158   */
   159  APR_DECLARE(void) apr_allocator_mutex_set(apr_allocator_t *allocator,
   160                                            apr_thread_mutex_t *mutex)
   161                    __attribute__((nonnull(1)));
   162  
   163  /**
   164   * Get the mutex currently set for the allocator
   165   * @param allocator The allocator
   166   */
   167  APR_DECLARE(apr_thread_mutex_t *) apr_allocator_mutex_get(
   168                                            apr_allocator_t *allocator)
   169                                    __attribute__((nonnull(1)));
   170  
   171  #endif /* APR_HAS_THREADS */
   172  
   173  /** @} */
   174  
   175  #ifdef __cplusplus
   176  }
   177  #endif
   178  
   179  #endif /* !APR_ALLOCATOR_H */