external/bsd/ntp/dist/lib/isc/include/isc/quota.h

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