misc/apr_reslist.c

   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 #include <assert.h>
  18
  19 #include "apu.h"
  20 #include "apr_reslist.h"
  21 #include "apr_errno.h"
  22 #include "apr_strings.h"
  23 #include "apr_thread_mutex.h"
  24 #include "apr_thread_cond.h"
  25 #include "apr_ring.h"
  26
  27 /**
  28  * A single resource element.
  29  */
  30 struct apr_res_t {
  31     apr_time_t freed;
  32     void *opaque;
  33     APR_RING_ENTRY(apr_res_t) link;
  34 };
  35 typedef struct apr_res_t apr_res_t;
  36
  37 /**
  38  * A ring of resources representing the list of available resources.
  39  */
  40 APR_RING_HEAD(apr_resring_t, apr_res_t);
  41 typedef struct apr_resring_t apr_resring_t;
  42
  43 struct apr_reslist_t {
  44     apr_pool_t *pool; /* the pool used in constructor and destructor calls */
  45     int ntotal;     /* total number of resources managed by this list */
  46     int nidle;      /* number of available resources */
  47     int min;  /* desired minimum number of available resources */
  48     int smax; /* soft maximum on the total number of resources */
  49     int hmax; /* hard maximum on the total number of resources */
  50     apr_interval_time_t ttl; /* TTL when we have too many resources */
  51     apr_interval_time_t timeout; /* Timeout for waiting on resource */
  52     apr_reslist_constructor constructor;
  53     apr_reslist_destructor destructor;
  54     void *params; /* opaque data passed to constructor and destructor calls */
  55     apr_resring_t avail_list;
  56     apr_resring_t free_list;
  57 #if APR_HAS_THREADS
  58     apr_thread_mutex_t *listlock;
  59     apr_thread_cond_t *avail;
  60 #endif
  61 };
  62
  63 /**
  64  * Grab a resource from the front of the resource list.
  65  * Assumes: that the reslist is locked.
  66  */
  67 static apr_res_t *pop_resource(apr_reslist_t *reslist)
  68 {
  69     apr_res_t *res;
  70     res = APR_RING_FIRST(&reslist->avail_list);
  71     APR_RING_REMOVE(res, link);
  72     reslist->nidle--;
  73     return res;
  74 }
  75
  76 /**
  77  * Add a resource to the beginning of the list, set the time at which
  78  * it was added to the list.
  79  * Assumes: that the reslist is locked.
  80  */
  81 static void push_resource(apr_reslist_t *reslist, apr_res_t *resource)
  82 {
  83     APR_RING_INSERT_HEAD(&reslist->avail_list, resource, apr_res_t, link);
  84     resource->freed = apr_time_now();
  85     reslist->nidle++;
  86 }
  87
  88 /**
  89  * Get an resource container from the free list or create a new one.
  90  */
  91 static apr_res_t *get_container(apr_reslist_t *reslist)
  92 {
  93     apr_res_t *res;
  94
  95     if (!APR_RING_EMPTY(&reslist->free_list, apr_res_t, link)) {
  96         res = APR_RING_FIRST(&reslist->free_list);
  97         APR_RING_REMOVE(res, link);
  98     }
  99     else
 100         res = apr_pcalloc(reslist->pool, sizeof(*res));
 101     return res;
 102 }
 103
 104 /**
 105  * Free up a resource container by placing it on the free list.
 106  */
 107 static void free_container(apr_reslist_t *reslist, apr_res_t *container)
 108 {
 109     APR_RING_INSERT_TAIL(&reslist->free_list, container, apr_res_t, link);
 110 }
 111
 112 /**
 113  * Create a new resource and return it.
 114  * Assumes: that the reslist is locked.
 115  */
 116 static apr_status_t create_resource(apr_reslist_t *reslist, apr_res_t **ret_res)
 117 {
 118     apr_status_t rv;
 119     apr_res_t *res;
 120
 121     res = get_container(reslist);
 122
 123     rv = reslist->constructor(&res->opaque, reslist->params, reslist->pool);
 124
 125     *ret_res = res;
 126     return rv;
 127 }
 128
 129 /**
 130  * Destroy a single idle resource.
 131  * Assumes: that the reslist is locked.
 132  */
 133 static apr_status_t destroy_resource(apr_reslist_t *reslist, apr_res_t *res)
 134 {
 135     return reslist->destructor(res->opaque, reslist->params, reslist->pool);
 136 }
 137
 138 static apr_status_t reslist_cleanup(void *data_)
 139 {
 140     apr_status_t rv = APR_SUCCESS;
 141     apr_reslist_t *rl = data_;
 142     apr_res_t *res;
 143
 144 #if APR_HAS_THREADS
 145     apr_thread_mutex_lock(rl->listlock);
 146 #endif
 147
 148     while (rl->nidle > 0) {
 149         apr_status_t rv1;
 150         res = pop_resource(rl);
 151         rl->ntotal--;
 152         rv1 = destroy_resource(rl, res);
 153         if (rv1 != APR_SUCCESS) {
 154             rv = rv1;  /* loses info in the unlikely event of
 155                         * multiple *different* failures */
 156         }
 157         free_container(rl, res);
 158     }
 159
 160     assert(rl->nidle == 0);
 161     assert(rl->ntotal == 0);
 162
 163 #if APR_HAS_THREADS
 164     apr_thread_mutex_unlock(rl->listlock);
 165     apr_thread_mutex_destroy(rl->listlock);
 166     apr_thread_cond_destroy(rl->avail);
 167 #endif
 168
 169     return rv;
 170 }
 171
 172 /**
 173  * Perform routine maintenance on the resource list. This call
 174  * may instantiate new resources or expire old resources.
 175  */
 176 static apr_status_t reslist_maint(apr_reslist_t *reslist)
 177 {
 178     apr_time_t now;
 179     apr_status_t rv;
 180     apr_res_t *res;
 181     int created_one = 0;
 182
 183 #if APR_HAS_THREADS
 184     apr_thread_mutex_lock(reslist->listlock);
 185 #endif
 186
 187     /* Check if we need to create more resources, and if we are allowed to. */
 188     while (reslist->nidle < reslist->min && reslist->ntotal < reslist->hmax) {
 189         /* Create the resource */
 190         rv = create_resource(reslist, &res);
 191         if (rv != APR_SUCCESS) {
 192             free_container(reslist, res);
 193 #if APR_HAS_THREADS
 194             apr_thread_mutex_unlock(reslist->listlock);
 195 #endif
 196             return rv;
 197         }
 198         /* Add it to the list */
 199         push_resource(reslist, res);
 200         /* Update our counters */
 201         reslist->ntotal++;
 202         /* If someone is waiting on that guy, wake them up. */
 203 #if APR_HAS_THREADS
 204         rv = apr_thread_cond_signal(reslist->avail);
 205         if (rv != APR_SUCCESS) {
 206             apr_thread_mutex_unlock(reslist->listlock);
 207             return rv;
 208         }
 209 #endif
 210         created_one++;
 211     }
 212
 213     /* We don't need to see if we're over the max if we were under it before */
 214     if (created_one) {
 215 #if APR_HAS_THREADS
 216         apr_thread_mutex_unlock(reslist->listlock);
 217 #endif
 218         return APR_SUCCESS;
 219     }
 220
 221     /* Check if we need to expire old resources */
 222     now = apr_time_now();
 223     while (reslist->nidle > reslist->smax && reslist->nidle > 0) {
 224         /* Peak at the last resource in the list */
 225         res = APR_RING_LAST(&reslist->avail_list);
 226         /* See if the oldest entry should be expired */
 227         if (now - res->freed < reslist->ttl) {
 228             /* If this entry is too young, none of the others
 229              * will be ready to be expired either, so we are done. */
 230             break;
 231         }
 232         APR_RING_REMOVE(res, link);
 233         reslist->nidle--;
 234         reslist->ntotal--;
 235         rv = destroy_resource(reslist, res);
 236         free_container(reslist, res);
 237         if (rv != APR_SUCCESS) {
 238 #if APR_HAS_THREADS
 239             apr_thread_mutex_unlock(reslist->listlock);
 240 #endif
 241             return rv;
 242         }
 243     }
 244
 245 #if APR_HAS_THREADS
 246     apr_thread_mutex_unlock(reslist->listlock);
 247 #endif
 248     return APR_SUCCESS;
 249 }
 250
 251 APU_DECLARE(apr_status_t) apr_reslist_create(apr_reslist_t **reslist,
 252                                              int min, int smax, int hmax,
 253                                              apr_interval_time_t ttl,
 254                                              apr_reslist_constructor con,
 255                                              apr_reslist_destructor de,
 256                                              void *params,
 257                                              apr_pool_t *pool)
 258 {
 259     apr_status_t rv;
 260     apr_reslist_t *rl;
 261
 262     /* Do some sanity checks so we don't thrash around in the
 263      * maintenance routine later. */
 264     if (min < 0 || min > smax || min > hmax || smax > hmax || hmax == 0 ||
 265         ttl < 0) {
 266         return APR_EINVAL;
 267     }
 268
 269 #if !APR_HAS_THREADS
 270     /* There can be only one resource when we have no threads. */
 271     if (min > 0) {
 272         min = 1;
 273     }
 274     if (smax > 0) {
 275         smax = 1;
 276     }
 277     hmax = 1;
 278 #endif
 279
 280     rl = apr_pcalloc(pool, sizeof(*rl));
 281     rl->pool = pool;
 282     rl->min = min;
 283     rl->smax = smax;
 284     rl->hmax = hmax;
 285     rl->ttl = ttl;
 286     rl->constructor = con;
 287     rl->destructor = de;
 288     rl->params = params;
 289
 290     APR_RING_INIT(&rl->avail_list, apr_res_t, link);
 291     APR_RING_INIT(&rl->free_list, apr_res_t, link);
 292
 293 #if APR_HAS_THREADS
 294     rv = apr_thread_mutex_create(&rl->listlock, APR_THREAD_MUTEX_DEFAULT,
 295                                  pool);
 296     if (rv != APR_SUCCESS) {
 297         return rv;
 298     }
 299     rv = apr_thread_cond_create(&rl->avail, pool);
 300     if (rv != APR_SUCCESS) {
 301         return rv;
 302     }
 303 #endif
 304
 305     rv = reslist_maint(rl);
 306     if (rv != APR_SUCCESS) {
 307         return rv;
 308     }
 309
 310     /* Register a pool pre_cleanup.
 311      * This will ensure that reslist_cleanup is run BEFORE
 312      * any of the eventual child pools of this pool.
 313      * If an child pool was created inside apr_reslist_destructor,
 314      * this child pool can safely call apr_pool_destroy inside
 315      * apr_reslist_destructor thus safely detaching himself.
 316      */
 317     apr_pool_pre_cleanup_register(rl->pool, rl, reslist_cleanup);
 318
 319     *reslist = rl;
 320
 321     return APR_SUCCESS;
 322 }
 323
 324 APU_DECLARE(apr_status_t) apr_reslist_destroy(apr_reslist_t *reslist)
 325 {
 326     return apr_pool_cleanup_run(reslist->pool, reslist, reslist_cleanup);
 327 }
 328
 329 APU_DECLARE(apr_status_t) apr_reslist_acquire(apr_reslist_t *reslist,
 330                                               void **resource)
 331 {
 332     apr_status_t rv;
 333     apr_res_t *res;
 334     apr_time_t now;
 335
 336 #if APR_HAS_THREADS
 337     apr_thread_mutex_lock(reslist->listlock);
 338 #endif
 339     /* If there are idle resources on the available list, use
 340      * them right away. */
 341     now = apr_time_now();
 342     while (reslist->nidle > 0) {
 343         /* Pop off the first resource */
 344         res = pop_resource(reslist);
 345         if (reslist->ttl && (now - res->freed >= reslist->ttl)) {
 346             /* this res is expired - kill it */
 347             reslist->ntotal--;
 348             rv = destroy_resource(reslist, res);
 349             free_container(reslist, res);
 350             if (rv != APR_SUCCESS) {
 351 #if APR_HAS_THREADS
 352                 apr_thread_mutex_unlock(reslist->listlock);
 353 #endif
 354                 return rv;  /* FIXME: this might cause unnecessary fails */
 355             }
 356             continue;
 357         }
 358         *resource = res->opaque;
 359         free_container(reslist, res);
 360 #if APR_HAS_THREADS
 361         apr_thread_mutex_unlock(reslist->listlock);
 362 #endif
 363         return APR_SUCCESS;
 364     }
 365     /* If we've hit our max, block until we're allowed to create
 366      * a new one, or something becomes free. */
 367     while (reslist->ntotal >= reslist->hmax && reslist->nidle <= 0) {
 368 #if APR_HAS_THREADS
 369         if (reslist->timeout) {
 370             if ((rv = apr_thread_cond_timedwait(reslist->avail,
 371                 reslist->listlock, reslist->timeout)) != APR_SUCCESS) {
 372                 apr_thread_mutex_unlock(reslist->listlock);
 373                 return rv;
 374             }
 375         }
 376         else {
 377             apr_thread_cond_wait(reslist->avail, reslist->listlock);
 378         }
 379 #else
 380         return APR_EAGAIN;
 381 #endif
 382     }
 383     /* If we popped out of the loop, first try to see if there
 384      * are new resources available for immediate use. */
 385     if (reslist->nidle > 0) {
 386         res = pop_resource(reslist);
 387         *resource = res->opaque;
 388         free_container(reslist, res);
 389 #if APR_HAS_THREADS
 390         apr_thread_mutex_unlock(reslist->listlock);
 391 #endif
 392         return APR_SUCCESS;
 393     }
 394     /* Otherwise the reason we dropped out of the loop
 395      * was because there is a new slot available, so create
 396      * a resource to fill the slot and use it. */
 397     else {
 398         rv = create_resource(reslist, &res);
 399         if (rv == APR_SUCCESS) {
 400             reslist->ntotal++;
 401             *resource = res->opaque;
 402         }
 403         free_container(reslist, res);
 404 #if APR_HAS_THREADS
 405         apr_thread_mutex_unlock(reslist->listlock);
 406 #endif
 407         return rv;
 408     }
 409 }
 410
 411 APU_DECLARE(apr_status_t) apr_reslist_release(apr_reslist_t *reslist,
 412                                               void *resource)
 413 {
 414     apr_res_t *res;
 415
 416 #if APR_HAS_THREADS
 417     apr_thread_mutex_lock(reslist->listlock);
 418 #endif
 419     res = get_container(reslist);
 420     res->opaque = resource;
 421     push_resource(reslist, res);
 422 #if APR_HAS_THREADS
 423     apr_thread_cond_signal(reslist->avail);
 424     apr_thread_mutex_unlock(reslist->listlock);
 425 #endif
 426
 427     return reslist_maint(reslist);
 428 }
 429
 430 APU_DECLARE(void) apr_reslist_timeout_set(apr_reslist_t *reslist,
 431                                           apr_interval_time_t timeout)
 432 {
 433     reslist->timeout = timeout;
 434 }
 435
 436 APU_DECLARE(apr_uint32_t) apr_reslist_acquired_count(apr_reslist_t *reslist)
 437 {
 438     apr_uint32_t count;
 439
 440 #if APR_HAS_THREADS
 441     apr_thread_mutex_lock(reslist->listlock);
 442 #endif
 443     count = reslist->ntotal - reslist->nidle;
 444 #if APR_HAS_THREADS
 445     apr_thread_mutex_unlock(reslist->listlock);
 446 #endif
 447
 448     return count;
 449 }
 450
 451 APU_DECLARE(apr_status_t) apr_reslist_invalidate(apr_reslist_t *reslist,
 452                                                  void *resource)
 453 {
 454     apr_status_t ret;
 455
 456     ret = reslist->destructor(resource, reslist->params, reslist->pool);
 457 #if APR_HAS_THREADS
 458     apr_thread_mutex_lock(reslist->listlock);
 459 #endif
 460     reslist->ntotal--;
 461 #if APR_HAS_THREADS
 462     apr_thread_cond_signal(reslist->avail);
 463     apr_thread_mutex_unlock(reslist->listlock);
 464 #endif
 465     return ret;
 466 }