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 #if APR_HAS_THREADS
00032 
00033 /**
00034  * @defgroup APR_Util_RL Resource List Routines
00035  * @ingroup APR_Util
00036  * @{
00037  * @warning
00038  * <strong><em>Resource list data types and routines are only available when
00039  * threads are enabled (i.e. APR_HAS_THREADS is not zero).</em></strong>
00040  */
00041 
00042 #ifdef __cplusplus
00043 extern "C" {
00044 #endif /* __cplusplus */
00045 
00046 /** Opaque resource list object */
00047 typedef struct apr_reslist_t apr_reslist_t;
00048 
00049 /* Generic constructor called by resource list when it needs to create a
00050  * resource.
00051  * @param resource opaque resource
00052  * @param param flags
00053  * @param pool  Pool
00054  */
00055 typedef apr_status_t (*apr_reslist_constructor)(void **resource, void *params,
00056                                                 apr_pool_t *pool);
00057 
00058 /* Generic destructor called by resource list when it needs to destroy a
00059  * resource.
00060  * @param resource opaque resource
00061  * @param param flags
00062  * @param pool  Pool
00063  */
00064 typedef apr_status_t (*apr_reslist_destructor)(void *resource, void *params,
00065                                                apr_pool_t *pool);
00066 
00067 /**
00068  * Create a new resource list with the following parameters:
00069  * @param reslist An address where the pointer to the new resource
00070  *                list will be stored.
00071  * @param min Allowed minimum number of available resources. Zero
00072  *            creates new resources only when needed.
00073  * @param smax Resources will be destroyed during reslist maintenance to
00074  *             meet this maximum restriction as they expire (reach their ttl).
00075  * @param hmax Absolute maximum limit on the number of total resources.
00076  * @param ttl If non-zero, sets the maximum amount of time in microseconds an
00077  *            unused resource is valid.  Any resource which has exceeded this
00078  *            time will be destroyed, either when encountered by
00079  *            apr_reslist_acquire() or during reslist maintenance.
00080  * @param con Constructor routine that is called to create a new resource.
00081  * @param de Destructor routine that is called to destroy an expired resource.
00082  * @param params Passed to constructor and deconstructor
00083  * @param pool The pool from which to create this resource list. Also the
00084  *             same pool that is passed to the constructor and destructor
00085  *             routines.
00086  * @warning If you're creating a sub-pool of the pool passed into this
00087  *          function in your constructor, you will need to follow some rules
00088  *          when it comes to destruction of that sub-pool, as calling
00089  *          apr_pool_destroy() outright on it in your destructor may create
00090  *          double free situations. That is because by the time destructor is
00091  *          called, the sub-pool may have already been destroyed. This also
00092  *          means that in the destructor, memory from the sub-pool should be
00093  *          treated as invalid. For examples of how to do this correctly, see
00094  *          mod_dbd of Apache 2.2 and memcache support in APR Util 1.3.
00095  */
00096 APU_DECLARE(apr_status_t) apr_reslist_create(apr_reslist_t **reslist,
00097                                              int min, int smax, int hmax,
00098                                              apr_interval_time_t ttl,
00099                                              apr_reslist_constructor con,
00100                                              apr_reslist_destructor de,
00101                                              void *params,
00102                                              apr_pool_t *pool);
00103 
00104 /**
00105  * Destroy the given resource list and all resources controlled by
00106  * this list.
00107  * FIXME: Should this block until all resources become available,
00108  *        or maybe just destroy all the free ones, or maybe destroy
00109  *        them even though they might be in use by something else?
00110  *        Currently it will abort if there are resources that haven't
00111  *        been released, so there is an assumption that all resources
00112  *        have been released to the list before calling this function.
00113  * @param reslist The reslist to destroy
00114  */
00115 APU_DECLARE(apr_status_t) apr_reslist_destroy(apr_reslist_t *reslist);
00116 
00117 /**
00118  * Retrieve a resource from the list, creating a new one if necessary.
00119  * If we have met our maximum number of resources, we will block
00120  * until one becomes available.
00121  */
00122 APU_DECLARE(apr_status_t) apr_reslist_acquire(apr_reslist_t *reslist,
00123                                               void **resource);
00124 
00125 /**
00126  * Return a resource back to the list of available resources.
00127  */
00128 APU_DECLARE(apr_status_t) apr_reslist_release(apr_reslist_t *reslist,
00129                                               void *resource);
00130 
00131 /**
00132  * Set the timeout the acquire will wait for a free resource
00133  * when the maximum number of resources is exceeded.
00134  * @param reslist The resource list.
00135  * @param timeout Timeout to wait. The zero waits forever.
00136  */
00137 APU_DECLARE(void) apr_reslist_timeout_set(apr_reslist_t *reslist,
00138                                           apr_interval_time_t timeout);
00139 
00140 /**
00141  * Return the number of outstanding resources.
00142  * @param reslist The resource list.
00143  */
00144 APU_DECLARE(apr_uint32_t) apr_reslist_acquired_count(apr_reslist_t *reslist);
00145 
00146 /**
00147  * Invalidate a resource in the pool - e.g. a database connection
00148  * that returns a "lost connection" error and can't be restored.
00149  * Use this instead of apr_reslist_release if the resource is bad.
00150  */
00151 APU_DECLARE(apr_status_t) apr_reslist_invalidate(apr_reslist_t *reslist,
00152                                                  void *resource);
00153 
00154 
00155 #ifdef __cplusplus
00156 }
00157 #endif
00158 
00159 /** @} */
00160 
00161 #endif  /* APR_HAS_THREADS */
00162 
00163 #endif  /* ! APR_RESLIST_H */
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines