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  */
00038 
00039 #ifdef __cplusplus
00040 extern "C" {
00041 #endif /* __cplusplus */
00042 
00043 /** Opaque resource list object */
00044 typedef struct apr_reslist_t apr_reslist_t;
00045 
00046 /* Generic constructor called by resource list when it needs to create a
00047  * resource.
00048  * @param resource opaque resource
00049  * @param param flags
00050  * @param pool  Pool
00051  */
00052 typedef apr_status_t (*apr_reslist_constructor)(void **resource, void *params,
00053                                                 apr_pool_t *pool);
00054 
00055 /* Generic destructor called by resource list when it needs to destroy a
00056  * resource.
00057  * @param resource opaque resource
00058  * @param param flags
00059  * @param pool  Pool
00060  */
00061 typedef apr_status_t (*apr_reslist_destructor)(void *resource, void *params,
00062                                                apr_pool_t *pool);
00063 
00064 /**
00065  * Create a new resource list with the following parameters:
00066  * @param reslist An address where the pointer to the new resource
00067  *                list will be stored.
00068  * @param pool The pool to use for local storage and management
00069  * @param min Allowed minimum number of available resources. Zero
00070  *            creates new resources only when needed.
00071  * @param smax Resources will be destroyed to meet this maximum
00072  *             restriction as they expire.
00073  * @param hmax Absolute maximum limit on the number of total resources.
00074  * @param ttl If non-zero, sets the maximum amount of time a resource
00075  *               may be available while exceeding the soft limit.
00076  * @param con Constructor routine that is called to create a new resource.
00077  * @param de Destructor routine that is called to destroy an expired resource.
00078  * @param params Passed to constructor and deconstructor
00079  * @param pool The pool from which to create this resoure list. Also the
00080  *             same pool that is passed to the constructor and destructor
00081  *             routines.
00082  */
00083 APU_DECLARE(apr_status_t) apr_reslist_create(apr_reslist_t **reslist,
00084                                              int min, int smax, int hmax,
00085                                              apr_interval_time_t ttl,
00086                                              apr_reslist_constructor con,
00087                                              apr_reslist_destructor de,
00088                                              void *params,
00089                                              apr_pool_t *pool);
00090 
00091 /**
00092  * Destroy the given resource list and all resources controlled by
00093  * this list.
00094  * FIXME: Should this block until all resources become available,
00095  *        or maybe just destroy all the free ones, or maybe destroy
00096  *        them even though they might be in use by something else?
00097  *        Currently it will abort if there are resources that haven't
00098  *        been released, so there is an assumption that all resources
00099  *        have been released to the list before calling this function.
00100  * @param reslist The reslist to destroy
00101  */
00102 APU_DECLARE(apr_status_t) apr_reslist_destroy(apr_reslist_t *reslist);
00103 
00104 /**
00105  * Retrieve a resource from the list, creating a new one if necessary.
00106  * If we have met our maximum number of resources, we will block
00107  * until one becomes available.
00108  */
00109 APU_DECLARE(apr_status_t) apr_reslist_acquire(apr_reslist_t *reslist,
00110                                               void **resource);
00111 
00112 /**
00113  * Return a resource back to the list of available resources.
00114  */
00115 APU_DECLARE(apr_status_t) apr_reslist_release(apr_reslist_t *reslist,
00116                                               void *resource);
00117 
00118 /**
00119  * Set the timeout the acquire will wait for a free resource
00120  * when the maximum number of resources is exceeded.
00121  * @param reslist The resource list.
00122  * @param timeout Timeout to wait. The zero waits forewer.
00123  */
00124 APU_DECLARE(void) apr_reslist_timeout_set(apr_reslist_t *reslist,
00125                                           apr_interval_time_t timeout);
00126 
00127 /**
00128  * Invalidate a resource in the pool - e.g. a database connection
00129  * that returns a "lost connection" error and can't be restored.
00130  * Use this instead of apr_reslist_release if the resource is bad.
00131  */
00132 APU_DECLARE(apr_status_t) apr_reslist_invalidate(apr_reslist_t *reslist,
00133                                                  void *resource);
00134 
00135 
00136 #ifdef __cplusplus
00137 }
00138 #endif
00139 
00140 /** @} */
00141 
00142 #endif  /* APR_HAS_THREADS */
00143 
00144 #endif  /* ! APR_RESLIST_H */

Generated on Wed Nov 28 16:05:13 2007 for Apache Portable Runtime by  doxygen 1.5.4