github.com/krum110487/go-htaccess@v0.0.0-20240316004156-60641c8e7598/tests/data/apache_2_2_34/include/apr_reslist.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_RESLIST_H
    18  #define APR_RESLIST_H
    19  
    20  /** 
    21   * @file apr_reslist.h
    22   * @brief APR-UTIL Resource List Routines
    23   */
    24  
    25  #include "apr.h"
    26  #include "apu.h"
    27  #include "apr_pools.h"
    28  #include "apr_errno.h"
    29  #include "apr_time.h"
    30  
    31  /**
    32   * @defgroup APR_Util_RL Resource List Routines
    33   * @ingroup APR_Util
    34   * @{
    35   */
    36  
    37  #ifdef __cplusplus
    38  extern "C" {
    39  #endif /* __cplusplus */
    40  
    41  /** Opaque resource list object */
    42  typedef struct apr_reslist_t apr_reslist_t;
    43  
    44  /* Generic constructor called by resource list when it needs to create a
    45   * resource.
    46   * @param resource opaque resource
    47   * @param params flags
    48   * @param pool  Pool
    49   */
    50  typedef apr_status_t (*apr_reslist_constructor)(void **resource, void *params,
    51                                                  apr_pool_t *pool);
    52  
    53  /* Generic destructor called by resource list when it needs to destroy a
    54   * resource.
    55   * @param resource opaque resource
    56   * @param params flags
    57   * @param pool  Pool
    58   */
    59  typedef apr_status_t (*apr_reslist_destructor)(void *resource, void *params,
    60                                                 apr_pool_t *pool);
    61  
    62  /* Cleanup order modes */
    63  #define APR_RESLIST_CLEANUP_DEFAULT  0       /**< default pool cleanup */
    64  #define APR_RESLIST_CLEANUP_FIRST    1       /**< use pool pre cleanup */
    65  
    66  /**
    67   * Create a new resource list with the following parameters:
    68   * @param reslist An address where the pointer to the new resource
    69   *                list will be stored.
    70   * @param min Allowed minimum number of available resources. Zero
    71   *            creates new resources only when needed.
    72   * @param smax Resources will be destroyed during reslist maintenance to
    73   *             meet this maximum restriction as they expire (reach their ttl).
    74   * @param hmax Absolute maximum limit on the number of total resources.
    75   * @param ttl If non-zero, sets the maximum amount of time in microseconds an
    76   *            unused resource is valid.  Any resource which has exceeded this
    77   *            time will be destroyed, either when encountered by
    78   *            apr_reslist_acquire() or during reslist maintenance.
    79   * @param con Constructor routine that is called to create a new resource.
    80   * @param de Destructor routine that is called to destroy an expired resource.
    81   * @param params Passed to constructor and deconstructor
    82   * @param pool The pool from which to create this resource list. Also the
    83   *             same pool that is passed to the constructor and destructor
    84   *             routines.
    85   * @remark If APR has been compiled without thread support, hmax will be
    86   *         automatically set to 1 and values of min and smax will be forced to
    87   *         1 for any non-zero value.
    88   */
    89  APU_DECLARE(apr_status_t) apr_reslist_create(apr_reslist_t **reslist,
    90                                               int min, int smax, int hmax,
    91                                               apr_interval_time_t ttl,
    92                                               apr_reslist_constructor con,
    93                                               apr_reslist_destructor de,
    94                                               void *params,
    95                                               apr_pool_t *pool);
    96  
    97  /**
    98   * Destroy the given resource list and all resources controlled by
    99   * this list.
   100   * FIXME: Should this block until all resources become available,
   101   *        or maybe just destroy all the free ones, or maybe destroy
   102   *        them even though they might be in use by something else?
   103   *        Currently it will abort if there are resources that haven't
   104   *        been released, so there is an assumption that all resources
   105   *        have been released to the list before calling this function.
   106   * @param reslist The reslist to destroy
   107   */
   108  APU_DECLARE(apr_status_t) apr_reslist_destroy(apr_reslist_t *reslist);
   109  
   110  /**
   111   * Retrieve a resource from the list, creating a new one if necessary.
   112   * If we have met our maximum number of resources, we will block
   113   * until one becomes available.
   114   * @param reslist The resource list.
   115   * @param resource An address where the pointer to the resource
   116   *                will be stored.
   117   */
   118  APU_DECLARE(apr_status_t) apr_reslist_acquire(apr_reslist_t *reslist,
   119                                                void **resource);
   120  
   121  /**
   122   * Return a resource back to the list of available resources.
   123   * @param reslist The resource list.
   124   * @param resource The resource to return to the list.
   125   */
   126  APU_DECLARE(apr_status_t) apr_reslist_release(apr_reslist_t *reslist,
   127                                                void *resource);
   128  
   129  /**
   130   * Set the timeout the acquire will wait for a free resource
   131   * when the maximum number of resources is exceeded.
   132   * @param reslist The resource list.
   133   * @param timeout Timeout to wait. The zero waits forever.
   134   */
   135  APU_DECLARE(void) apr_reslist_timeout_set(apr_reslist_t *reslist,
   136                                            apr_interval_time_t timeout);
   137  
   138  /**
   139   * Return the number of outstanding resources.
   140   * @param reslist The resource list.
   141   */
   142  APU_DECLARE(apr_uint32_t) apr_reslist_acquired_count(apr_reslist_t *reslist);
   143  
   144  /**
   145   * Invalidate a resource in the pool - e.g. a database connection
   146   * that returns a "lost connection" error and can't be restored.
   147   * Use this instead of apr_reslist_release if the resource is bad.
   148   * @param reslist The resource list.
   149   * @param resource The resource to invalidate.
   150   */
   151  APU_DECLARE(apr_status_t) apr_reslist_invalidate(apr_reslist_t *reslist,
   152                                                   void *resource);
   153  
   154  /**
   155   * Perform routine maintenance on the resource list. This call
   156   * may instantiate new resources or expire old resources.
   157   * @param reslist The resource list.
   158   */
   159  APU_DECLARE(apr_status_t) apr_reslist_maintain(apr_reslist_t *reslist);
   160  
   161  /**
   162   * Set reslist cleanup order.
   163   * @param reslist The resource list.
   164   * @param mode Cleanup order mode
   165   * <PRE>
   166   *           APR_RESLIST_CLEANUP_DEFAULT  default pool cleanup order
   167   *           APR_RESLIST_CLEANUP_FIRST    use pool pre cleanup
   168   * </PRE>
   169   * @remark If APR_RESLIST_CLEANUP_FIRST is used the destructors will
   170   * be called before child pools of the pool used to create the reslist
   171   * are destroyed. This allows to explicitly destroy the child pools
   172   * inside reslist destructors.
   173   */
   174  APU_DECLARE(void) apr_reslist_cleanup_order_set(apr_reslist_t *reslist,
   175                                                  apr_uint32_t mode);
   176  
   177  #ifdef __cplusplus
   178  }
   179  #endif
   180  
   181  /** @} */
   182  
   183  #endif  /* ! APR_RESLIST_H */