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 */ |