Apache Portable Runtime
apr_reslist.h
Go to the documentation of this file.
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more
00002  * contributor license agreements.  See the NOTICE file distributed with
00003  * this work for additional information regarding copyright ownership.
00004  * The ASF licenses this file to You under the Apache License, Version 2.0
00005  * (the "License"); you may not use this file except in compliance with
00006  * the License.  You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef APR_RESLIST_H
00018 #define APR_RESLIST_H
00019 
00020 /** 
00021  * @file apr_reslist.h
00022  * @brief APR-UTIL Resource List Routines
00023  */
00024 
00025 #include "apr.h"
00026 #include "apu.h"
00027 #include "apr_pools.h"
00028 #include "apr_errno.h"
00029 #include "apr_time.h"
00030 
00031 /**
00032  * @defgroup APR_Util_RL Resource List Routines
00033  * @ingroup APR
00034  * @{
00035  */
00036 
00037 #ifdef __cplusplus
00038 extern "C" {
00039 #endif /* __cplusplus */
00040 
00041 /** Opaque resource list object */
00042 typedef struct apr_reslist_t apr_reslist_t;
00043 
00044 /* Generic constructor called by resource list when it needs to create a
00045  * resource.
00046  * @param resource opaque resource
00047  * @param param flags
00048  * @param pool  Pool
00049  */
00050 typedef apr_status_t (*apr_reslist_constructor)(void **resource, void *params,
00051                                                 apr_pool_t *pool);
00052 
00053 /* Generic destructor called by resource list when it needs to destroy a
00054  * resource.
00055  * @param resource opaque resource
00056  * @param param flags
00057  * @param pool  Pool
00058  */
00059 typedef apr_status_t (*apr_reslist_destructor)(void *resource, void *params,
00060                                                apr_pool_t *pool);
00061 
00062 /* Cleanup order modes */
00063 #define APR_RESLIST_CLEANUP_DEFAULT  0       /**< default pool cleanup */
00064 #define APR_RESLIST_CLEANUP_FIRST    1       /**< use pool pre cleanup */
00065 
00066 /**
00067  * Create a new resource list with the following parameters:
00068  * @param reslist An address where the pointer to the new resource
00069  *                list will be stored.
00070  * @param min Allowed minimum number of available resources. Zero
00071  *            creates new resources only when needed.
00072  * @param smax Resources will be destroyed during reslist maintenance to
00073  *             meet this maximum restriction as they expire (reach their ttl).
00074  * @param hmax Absolute maximum limit on the number of total resources.
00075  * @param ttl If non-zero, sets the maximum amount of time in microseconds an
00076  *            unused resource is valid.  Any resource which has exceeded this
00077  *            time will be destroyed, either when encountered by
00078  *            apr_reslist_acquire() or during reslist maintenance.
00079  * @param con Constructor routine that is called to create a new resource.
00080  * @param de Destructor routine that is called to destroy an expired resource.
00081  * @param params Passed to constructor and deconstructor
00082  * @param pool The pool from which to create this resource list. Also the
00083  *             same pool that is passed to the constructor and destructor
00084  *             routines.
00085  * @remark If APR has been compiled without thread support, hmax will be
00086  *         automatically set to 1 and values of min and smax will be forced to
00087  *         1 for any non-zero value.
00088  */
00089 APR_DECLARE(apr_status_t) apr_reslist_create(apr_reslist_t **reslist,
00090                                              int min, int smax, int hmax,
00091                                              apr_interval_time_t ttl,
00092                                              apr_reslist_constructor con,
00093                                              apr_reslist_destructor de,
00094                                              void *params,
00095                                              apr_pool_t *pool);
00096 
00097 /**
00098  * Destroy the given resource list and all resources controlled by
00099  * this list.
00100  * FIXME: Should this block until all resources become available,
00101  *        or maybe just destroy all the free ones, or maybe destroy
00102  *        them even though they might be in use by something else?
00103  *        Currently it will abort if there are resources that haven't
00104  *        been released, so there is an assumption that all resources
00105  *        have been released to the list before calling this function.
00106  * @param reslist The reslist to destroy
00107  */
00108 APR_DECLARE(apr_status_t) apr_reslist_destroy(apr_reslist_t *reslist);
00109 
00110 /**
00111  * Retrieve a resource from the list, creating a new one if necessary.
00112  * If we have met our maximum number of resources, we will block
00113  * until one becomes available.
00114  */
00115 APR_DECLARE(apr_status_t) apr_reslist_acquire(apr_reslist_t *reslist,
00116                                               void **resource);
00117 
00118 /**
00119  * Return a resource back to the list of available resources.
00120  */
00121 APR_DECLARE(apr_status_t) apr_reslist_release(apr_reslist_t *reslist,
00122                                               void *resource);
00123 
00124 /**
00125  * Set the timeout the acquire will wait for a free resource
00126  * when the maximum number of resources is exceeded.
00127  * @param reslist The resource list.
00128  * @param timeout Timeout to wait. The zero waits forever.
00129  */
00130 APR_DECLARE(void) apr_reslist_timeout_set(apr_reslist_t *reslist,
00131                                           apr_interval_time_t timeout);
00132 
00133 /**
00134  * Return the number of outstanding resources.
00135  * @param reslist The resource list.
00136  */
00137 APR_DECLARE(apr_uint32_t) apr_reslist_acquired_count(apr_reslist_t *reslist);
00138 
00139 /**
00140  * Invalidate a resource in the pool - e.g. a database connection
00141  * that returns a "lost connection" error and can't be restored.
00142  * Use this instead of apr_reslist_release if the resource is bad.
00143  */
00144 APR_DECLARE(apr_status_t) apr_reslist_invalidate(apr_reslist_t *reslist,
00145                                                  void *resource);
00146 
00147 /**
00148  * Perform routine maintenance on the resource list. This call
00149  * may instantiate new resources or expire old resources.
00150  * @param reslist The resource list.
00151  */
00152 APR_DECLARE(apr_status_t) apr_reslist_maintain(apr_reslist_t *reslist);
00153 
00154 /**
00155  * Set reslist cleanup order.
00156  * @param reslist The resource list.
00157  * @param mode Cleanup order mode
00158  * <PRE>
00159  *           APR_RESLIST_CLEANUP_DEFAULT  default pool cleanup order
00160  *           APR_RESLIST_CLEANUP_FIRST    use pool pre cleanup
00161  * </PRE>
00162  * @remark If APR_RESLIST_CLEANUP_FIRST is used the destructors will
00163  * be called before child pools of the pool used to create the reslist
00164  * are destroyed. This allows to explicitly destroy the child pools
00165  * inside reslist destructors.
00166  */
00167 APR_DECLARE(void) apr_reslist_cleanup_order_set(apr_reslist_t *reslist,
00168                                                 apr_uint32_t mode);
00169 
00170 #ifdef __cplusplus
00171 }
00172 #endif
00173 
00174 /** @} */
00175 
00176 #endif  /* ! APR_RESLIST_H */
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines