contrib/bind/lib/isc/include/isc/quota.h

   1 /*
   2  * Copyright (C) 2004, 2005, 2007  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 2000, 2001  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and/or distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  * PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 /* $Id: quota.h,v 1.16 2007/06/19 23:47:18 tbox Exp $ */
  19
  20 #ifndef ISC_QUOTA_H
  21 #define ISC_QUOTA_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file isc/quota.h
  28  *
  29  * \brief The isc_quota_t object is a simple helper object for implementing
  30  * quotas on things like the number of simultaneous connections to
  31  * a server.  It keeps track of the amount of quota in use, and
  32  * encapsulates the locking necessary to allow multiple tasks to
  33  * share a quota.
  34  */
  35
  36 /***
  37  *** Imports.
  38  ***/
  39
  40 #include <isc/lang.h>
  41 #include <isc/mutex.h>
  42 #include <isc/types.h>
  43
  44 /*****
  45  ***** Types.
  46  *****/
  47
  48 ISC_LANG_BEGINDECLS
  49
  50 /*% isc_quota structure */
  51 struct isc_quota {
  52         isc_mutex_t     lock; /*%< Locked by lock. */
  53         int             max;
  54         int             used;
  55         int             soft;
  56 };
  57
  58 isc_result_t
  59 isc_quota_init(isc_quota_t *quota, int max);
  60 /*%<
  61  * Initialize a quota object.
  62  *
  63  * Returns:
  64  *      ISC_R_SUCCESS
  65  *      Other error     Lock creation failed.
  66  */
  67
  68 void
  69 isc_quota_destroy(isc_quota_t *quota);
  70 /*%<
  71  * Destroy a quota object.
  72  */
  73
  74 void
  75 isc_quota_soft(isc_quota_t *quota, int soft);
  76 /*%<
  77  * Set a soft quota.
  78  */
  79
  80 void
  81 isc_quota_max(isc_quota_t *quota, int max);
  82 /*%<
  83  * Re-set a maximum quota.
  84  */
  85
  86 isc_result_t
  87 isc_quota_reserve(isc_quota_t *quota);
  88 /*%<
  89  * Attempt to reserve one unit of 'quota'.
  90  *
  91  * Returns:
  92  * \li  #ISC_R_SUCCESS          Success
  93  * \li  #ISC_R_SOFTQUOTA        Success soft quota reached
  94  * \li  #ISC_R_QUOTA            Quota is full
  95  */
  96
  97 void
  98 isc_quota_release(isc_quota_t *quota);
  99 /*%<
 100  * Release one unit of quota.
 101  */
 102
 103 isc_result_t
 104 isc_quota_attach(isc_quota_t *quota, isc_quota_t **p);
 105 /*%<
 106  * Like isc_quota_reserve, and also attaches '*p' to the
 107  * quota if successful (ISC_R_SUCCESS or ISC_R_SOFTQUOTA).
 108  */
 109
 110 void
 111 isc_quota_detach(isc_quota_t **p);
 112 /*%<
 113  * Like isc_quota_release, and also detaches '*p' from the
 114  * quota.
 115  */
 116
 117 ISC_LANG_ENDDECLS
 118
 119 #endif /* ISC_QUOTA_H */