refcount.h revision 047f369a62321dccf33ade14de9fb794d6aeacf5
1/*
2 * Copyright (C) 2004-2007, 2009  Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 2001, 2003  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: refcount.h,v 1.17 2009/09/29 23:48:04 tbox Exp $ */
19
20#ifndef ISC_REFCOUNT_H
21#define ISC_REFCOUNT_H 1
22
23#include <isc/atomic.h>
24#include <isc/lang.h>
25#include <isc/mutex.h>
26#include <isc/platform.h>
27#include <isc/types.h>
28#include <isc/util.h>
29
30/*! \file isc/refcount.h
31 * \brief Implements a locked reference counter.
32 *
33 * These functions may actually be
34 * implemented using macros, and implementations of these macros are below.
35 * The isc_refcount_t type should not be accessed directly, as its contents
36 * depend on the implementation.
37 */
38
39ISC_LANG_BEGINDECLS
40
41/*
42 * Function prototypes
43 */
44
45/*
46 * isc_result_t
47 * isc_refcount_init(isc_refcount_t *ref, unsigned int n);
48 *
49 * Initialize the reference counter.  There will be 'n' initial references.
50 *
51 * Requires:
52 *	ref != NULL
53 */
54
55/*
56 * void
57 * isc_refcount_destroy(isc_refcount_t *ref);
58 *
59 * Destroys a reference counter.
60 *
61 * Requires:
62 *	ref != NULL
63 *	The number of references is 0.
64 */
65
66/*
67 * void
68 * isc_refcount_increment(isc_refcount_t *ref, unsigned int *targetp);
69 * isc_refcount_increment0(isc_refcount_t *ref, unsigned int *targetp);
70 *
71 * Increments the reference count, returning the new value in targetp if it's
72 * not NULL.  The reference counter typically begins with the initial counter
73 * of 1, and will be destroyed once the counter reaches 0.  Thus,
74 * isc_refcount_increment() additionally requires the previous counter be
75 * larger than 0 so that an error which violates the usage can be easily
76 * caught.  isc_refcount_increment0() does not have this restriction.
77 *
78 * Requires:
79 *	ref != NULL.
80 */
81
82/*
83 * void
84 * isc_refcount_decrement(isc_refcount_t *ref, unsigned int *targetp);
85 *
86 * Decrements the reference count,  returning the new value in targetp if it's
87 * not NULL.
88 *
89 * Requires:
90 *	ref != NULL.
91 */
92
93
94/*
95 * Sample implementations
96 */
97#ifdef ISC_PLATFORM_USETHREADS
98#ifdef ISC_PLATFORM_HAVEXADD
99
100#define ISC_REFCOUNT_HAVEATOMIC 1
101
102typedef struct isc_refcount {
103	isc_int32_t refs;
104} isc_refcount_t;
105
106#define isc_refcount_destroy(rp) REQUIRE((rp)->refs == 0)
107#define isc_refcount_current(rp) ((unsigned int)((rp)->refs))
108
109#define isc_refcount_increment0(rp, tp)				\
110	do {							\
111		unsigned int *_tmp = (unsigned int *)(tp);	\
112		isc_int32_t prev;				\
113		prev = isc_atomic_xadd(&(rp)->refs, 1);		\
114		if (_tmp != NULL)				\
115			*_tmp = prev + 1;			\
116	} while (0)
117
118#define isc_refcount_increment(rp, tp)				\
119	do {							\
120		unsigned int *_tmp = (unsigned int *)(tp);	\
121		isc_int32_t prev;				\
122		prev = isc_atomic_xadd(&(rp)->refs, 1);		\
123		REQUIRE(prev > 0);				\
124		if (_tmp != NULL)				\
125			*_tmp = prev + 1;			\
126	} while (0)
127
128#define isc_refcount_decrement(rp, tp)				\
129	do {							\
130		unsigned int *_tmp = (unsigned int *)(tp);	\
131		isc_int32_t prev;				\
132		prev = isc_atomic_xadd(&(rp)->refs, -1);	\
133		REQUIRE(prev > 0);				\
134		if (_tmp != NULL)				\
135			*_tmp = prev - 1;			\
136	} while (0)
137
138#else  /* ISC_PLATFORM_HAVEXADD */
139
140typedef struct isc_refcount {
141	int refs;
142	isc_mutex_t lock;
143} isc_refcount_t;
144
145/*% Destroys a reference counter. */
146#define isc_refcount_destroy(rp)			\
147	do {						\
148		REQUIRE((rp)->refs == 0);		\
149		DESTROYLOCK(&(rp)->lock);		\
150	} while (0)
151
152#define isc_refcount_current(rp) ((unsigned int)((rp)->refs))
153
154/*% Increments the reference count, returning the new value in targetp if it's not NULL. */
155#define isc_refcount_increment0(rp, tp)				\
156	do {							\
157		unsigned int *_tmp = (unsigned int *)(tp);	\
158		LOCK(&(rp)->lock);				\
159		++((rp)->refs);					\
160		if (_tmp != NULL)				\
161			*_tmp = ((rp)->refs);			\
162		UNLOCK(&(rp)->lock);				\
163	} while (0)
164
165#define isc_refcount_increment(rp, tp)				\
166	do {							\
167		unsigned int *_tmp = (unsigned int *)(tp);	\
168		LOCK(&(rp)->lock);				\
169		REQUIRE((rp)->refs > 0);			\
170		++((rp)->refs);					\
171		if (_tmp != NULL)				\
172			*_tmp = ((rp)->refs);			\
173		UNLOCK(&(rp)->lock);				\
174	} while (0)
175
176/*% Decrements the reference count,  returning the new value in targetp if it's not NULL. */
177#define isc_refcount_decrement(rp, tp)				\
178	do {							\
179		unsigned int *_tmp = (unsigned int *)(tp);	\
180		LOCK(&(rp)->lock);				\
181		REQUIRE((rp)->refs > 0);			\
182		--((rp)->refs);					\
183		if (_tmp != NULL)				\
184			*_tmp = ((rp)->refs);			\
185		UNLOCK(&(rp)->lock);				\
186	} while (0)
187
188#endif /* ISC_PLATFORM_HAVEXADD */
189#else  /* ISC_PLATFORM_USETHREADS */
190
191typedef struct isc_refcount {
192	int refs;
193} isc_refcount_t;
194
195#define isc_refcount_destroy(rp) REQUIRE((rp)->refs == 0)
196#define isc_refcount_current(rp) ((unsigned int)((rp)->refs))
197
198#define isc_refcount_increment0(rp, tp)					\
199	do {								\
200		unsigned int *_tmp = (unsigned int *)(tp);		\
201		int _n = ++(rp)->refs;					\
202		if (_tmp != NULL)					\
203			*_tmp = _n;					\
204	} while (0)
205
206#define isc_refcount_increment(rp, tp)					\
207	do {								\
208		unsigned int *_tmp = (unsigned int *)(tp);		\
209		int _n;							\
210		REQUIRE((rp)->refs > 0);				\
211		_n = ++(rp)->refs;					\
212		if (_tmp != NULL)					\
213			*_tmp = _n;					\
214	} while (0)
215
216#define isc_refcount_decrement(rp, tp)					\
217	do {								\
218		unsigned int *_tmp = (unsigned int *)(tp);		\
219		int _n;							\
220		REQUIRE((rp)->refs > 0);				\
221		_n = --(rp)->refs;					\
222		if (_tmp != NULL)					\
223			*_tmp = _n;					\
224	} while (0)
225
226#endif /* ISC_PLATFORM_USETHREADS */
227
228isc_result_t
229isc_refcount_init(isc_refcount_t *ref, unsigned int n);
230
231ISC_LANG_ENDDECLS
232
233#endif /* ISC_REFCOUNT_H */
234