Apache Portable Runtime
apr_reslist.h
Go to the documentation of this file.
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
34  * @{
35  */
36 
37 #ifdef __cplusplus
38 extern "C" {
39 #endif /* __cplusplus */
40 
41 /** Opaque resource list object */
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  */
90  int min, int smax, int hmax,
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  */
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  */
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  */
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  */
136  apr_interval_time_t timeout);
137 
138 /**
139  * Return the number of outstanding resources.
140  * @param reslist The resource list.
141  */
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  */
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  */
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  */
175  apr_uint32_t mode);
176 
177 #ifdef __cplusplus
178 }
179 #endif
180 
181 /** @} */
182 
183 #endif /* ! APR_RESLIST_H */
apr_uint32_t apr_reslist_acquired_count(apr_reslist_t *reslist)
void apr_reslist_timeout_set(apr_reslist_t *reslist, apr_interval_time_t timeout)
struct apr_reslist_t apr_reslist_t
Definition: apr_reslist.h:42
void apr_reslist_cleanup_order_set(apr_reslist_t *reslist, apr_uint32_t mode)
apr_int64_t apr_interval_time_t
Definition: apr_time.h:55
APR memory allocation.
apr_status_t apr_reslist_acquire(apr_reslist_t *reslist, void **resource)
APR Error Codes.
#define APR_DECLARE(type)
Definition: apr.h:500
APR Platform Definitions.
apr_status_t apr_reslist_invalidate(apr_reslist_t *reslist, void *resource)
apr_status_t apr_reslist_release(apr_reslist_t *reslist, void *resource)
apr_status_t apr_reslist_maintain(apr_reslist_t *reslist)
struct apr_pool_t apr_pool_t
Definition: apr_pools.h:60
int apr_status_t
Definition: apr_errno.h:44
APR Time Library.
apr_status_t apr_reslist_create(apr_reslist_t **reslist, int min, int smax, int hmax, apr_interval_time_t ttl, apr_reslist_constructor con, apr_reslist_destructor de, void *params, apr_pool_t *pool)
apr_status_t apr_reslist_destroy(apr_reslist_t *reslist)