Annotation of win32/apache22/srclib/apr-util/include/apr_reslist.h, revision 1.1
1.1 ! moko 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 param 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 param 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: */
! 115: APU_DECLARE(apr_status_t) apr_reslist_acquire(apr_reslist_t *reslist,
! 116: void **resource);
! 117:
! 118: /**
! 119: * Return a resource back to the list of available resources.
! 120: */
! 121: APU_DECLARE(apr_status_t) apr_reslist_release(apr_reslist_t *reslist,
! 122: void *resource);
! 123:
! 124: /**
! 125: * Set the timeout the acquire will wait for a free resource
! 126: * when the maximum number of resources is exceeded.
! 127: * @param reslist The resource list.
! 128: * @param timeout Timeout to wait. The zero waits forever.
! 129: */
! 130: APU_DECLARE(void) apr_reslist_timeout_set(apr_reslist_t *reslist,
! 131: apr_interval_time_t timeout);
! 132:
! 133: /**
! 134: * Return the number of outstanding resources.
! 135: * @param reslist The resource list.
! 136: */
! 137: APU_DECLARE(apr_uint32_t) apr_reslist_acquired_count(apr_reslist_t *reslist);
! 138:
! 139: /**
! 140: * Invalidate a resource in the pool - e.g. a database connection
! 141: * that returns a "lost connection" error and can't be restored.
! 142: * Use this instead of apr_reslist_release if the resource is bad.
! 143: */
! 144: APU_DECLARE(apr_status_t) apr_reslist_invalidate(apr_reslist_t *reslist,
! 145: void *resource);
! 146:
! 147: /**
! 148: * Perform routine maintenance on the resource list. This call
! 149: * may instantiate new resources or expire old resources.
! 150: * @param reslist The resource list.
! 151: */
! 152: APU_DECLARE(apr_status_t) apr_reslist_maintain(apr_reslist_t *reslist);
! 153:
! 154: /**
! 155: * Set reslist cleanup order.
! 156: * @param reslist The resource list.
! 157: * @param mode Cleanup order mode
! 158: * <PRE>
! 159: * APR_RESLIST_CLEANUP_DEFAULT default pool cleanup order
! 160: * APR_RESLIST_CLEANUP_FIRST use pool pre cleanup
! 161: * </PRE>
! 162: * @remark If APR_RESLIST_CLEANUP_FIRST is used the destructors will
! 163: * be called before child pools of the pool used to create the reslist
! 164: * are destroyed. This allows to explicitly destroy the child pools
! 165: * inside reslist destructors.
! 166: */
! 167: APU_DECLARE(void) apr_reslist_cleanup_order_set(apr_reslist_t *reslist,
! 168: apr_uint32_t mode);
! 169:
! 170: #ifdef __cplusplus
! 171: }
! 172: #endif
! 173:
! 174: /** @} */
! 175:
! 176: #endif /* ! APR_RESLIST_H */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to apr_reslist.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / apache22 / srclib / apr-util / include