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
48ISC_LANG_BEGINDECLS
49
50/*% isc_quota structure */
51struct isc_quota {
52	isc_mutex_t	lock; /*%< Locked by lock. */
53	int 		max;
54	int 		used;
55	int		soft;
56};
57
58isc_result_t
59isc_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
68void
69isc_quota_destroy(isc_quota_t *quota);
70/*%<
71 * Destroy a quota object.
72 */
73
74void
75isc_quota_soft(isc_quota_t *quota, int soft);
76/*%<
77 * Set a soft quota.
78 */
79
80void
81isc_quota_max(isc_quota_t *quota, int max);
82/*%<
83 * Re-set a maximum quota.
84 */
85
86isc_result_t
87isc_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
97void
98isc_quota_release(isc_quota_t *quota);
99/*%<
100 * Release one unit of quota.
101 */
102
103isc_result_t
104isc_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
110void
111isc_quota_detach(isc_quota_t **p);
112/*%<
113 * Like isc_quota_release, and also detaches '*p' from the
114 * quota.
115 */
116
117ISC_LANG_ENDDECLS
118
119#endif /* ISC_QUOTA_H */
120