/*

[0] Fix | Delete

* Copyright (C) Internet Systems Consortium, Inc. ("ISC")

[1] Fix | Delete

*

[2] Fix | Delete

* This Source Code Form is subject to the terms of the Mozilla Public

[3] Fix | Delete

* License, v. 2.0. If a copy of the MPL was not distributed with this

[4] Fix | Delete

* file, you can obtain one at https://mozilla.org/MPL/2.0/.

[5] Fix | Delete

*

[6] Fix | Delete

* See the COPYRIGHT file distributed with this work for additional

[7] Fix | Delete

* information regarding copyright ownership.

[8] Fix | Delete

*/

[9] Fix | Delete

[10] Fix | Delete

[11] Fix | Delete

#ifndef ISC_REFCOUNT_H

[12] Fix | Delete

#define ISC_REFCOUNT_H 1

[13] Fix | Delete

[14] Fix | Delete

#include <inttypes.h>

[15] Fix | Delete

[16] Fix | Delete

#include <isc/assertions.h>

[17] Fix | Delete

#include <isc/atomic.h>

[18] Fix | Delete

#include <isc/error.h>

[19] Fix | Delete

#include <isc/lang.h>

[20] Fix | Delete

#include <isc/mutex.h>

[21] Fix | Delete

#include <isc/platform.h>

[22] Fix | Delete

#include <isc/types.h>

[23] Fix | Delete

[24] Fix | Delete

#if defined(ISC_PLATFORM_HAVESTDATOMIC)

[25] Fix | Delete

#if defined (__cplusplus)

[26] Fix | Delete

#include <isc/stdatomic.h>

[27] Fix | Delete

#else

[28] Fix | Delete

#include <stdatomic.h>

[29] Fix | Delete

#endif

[30] Fix | Delete

#endif

[31] Fix | Delete

[32] Fix | Delete

/*! \file isc/refcount.h

[33] Fix | Delete

* \brief Implements a locked reference counter.

[34] Fix | Delete

*

[35] Fix | Delete

* These functions may actually be

[36] Fix | Delete

* implemented using macros, and implementations of these macros are below.

[37] Fix | Delete

* The isc_refcount_t type should not be accessed directly, as its contents

[38] Fix | Delete

* depend on the implementation.

[39] Fix | Delete

*/

[40] Fix | Delete

[41] Fix | Delete

ISC_LANG_BEGINDECLS

[42] Fix | Delete

[43] Fix | Delete

/*

[44] Fix | Delete

* Function prototypes

[45] Fix | Delete

*/

[46] Fix | Delete

[47] Fix | Delete

/*

[48] Fix | Delete

* isc_result_t

[49] Fix | Delete

* isc_refcount_init(isc_refcount_t *ref, unsigned int n);

[50] Fix | Delete

*

[51] Fix | Delete

* Initialize the reference counter. There will be 'n' initial references.

[52] Fix | Delete

*

[53] Fix | Delete

* Requires:

[54] Fix | Delete

* ref != NULL

[55] Fix | Delete

*/

[56] Fix | Delete

[57] Fix | Delete

/*

[58] Fix | Delete

* void

[59] Fix | Delete

* isc_refcount_destroy(isc_refcount_t *ref);

[60] Fix | Delete

*

[61] Fix | Delete

* Destroys a reference counter.

[62] Fix | Delete

*

[63] Fix | Delete

* Requires:

[64] Fix | Delete

* ref != NULL

[65] Fix | Delete

* The number of references is 0.

[66] Fix | Delete

*/

[67] Fix | Delete

[68] Fix | Delete

/*

[69] Fix | Delete

* void

[70] Fix | Delete

* isc_refcount_increment(isc_refcount_t *ref, unsigned int *targetp);

[71] Fix | Delete

* isc_refcount_increment0(isc_refcount_t *ref, unsigned int *targetp);

[72] Fix | Delete

*

[73] Fix | Delete

* Increments the reference count, returning the new value in targetp if it's

[74] Fix | Delete

* not NULL. The reference counter typically begins with the initial counter

[75] Fix | Delete

* of 1, and will be destroyed once the counter reaches 0. Thus,

[76] Fix | Delete

* isc_refcount_increment() additionally requires the previous counter be

[77] Fix | Delete

* larger than 0 so that an error which violates the usage can be easily

[78] Fix | Delete

* caught. isc_refcount_increment0() does not have this restriction.

[79] Fix | Delete

*

[80] Fix | Delete

* Requires:

[81] Fix | Delete

* ref != NULL.

[82] Fix | Delete

*/

[83] Fix | Delete

[84] Fix | Delete

/*

[85] Fix | Delete

* void

[86] Fix | Delete

* isc_refcount_decrement(isc_refcount_t *ref, unsigned int *targetp);

[87] Fix | Delete

*

[88] Fix | Delete

* Decrements the reference count, returning the new value in targetp if it's

[89] Fix | Delete

* not NULL.

[90] Fix | Delete

*

[91] Fix | Delete

* Requires:

[92] Fix | Delete

* ref != NULL.

[93] Fix | Delete

*/

[94] Fix | Delete

[95] Fix | Delete

[96] Fix | Delete

/*

[97] Fix | Delete

* Sample implementations

[98] Fix | Delete

*/

[99] Fix | Delete

#ifdef ISC_PLATFORM_USETHREADS

[100] Fix | Delete

[101] Fix | Delete

#if defined(ISC_PLATFORM_HAVESTDATOMIC)

[102] Fix | Delete

# define ISC_REFCOUNT_HAVEATOMIC 1

[103] Fix | Delete

# define ISC_REFCOUNT_HAVESTDATOMIC 1

[104] Fix | Delete

#else /* defined(ISC_PLATFORM_HAVESTDATOMIC) */

[105] Fix | Delete

# if defined(ISC_PLATFORM_HAVEXADD)

[106] Fix | Delete

# define ISC_REFCOUNT_HAVEATOMIC 1

[107] Fix | Delete

# endif /* defined(ISC_PLATFORM_HAVEXADD */

[108] Fix | Delete

#endif /* !defined(ISC_REFCOUNT_HAVEATOMIC) */

[109] Fix | Delete

[110] Fix | Delete

#if defined(ISC_REFCOUNT_HAVEATOMIC)

[111] Fix | Delete

[112] Fix | Delete

typedef struct isc_refcount {

[113] Fix | Delete

#if defined(ISC_REFCOUNT_HAVESTDATOMIC)

[114] Fix | Delete

atomic_int_fast32_t refs;

[115] Fix | Delete

#else

[116] Fix | Delete

int32_t refs;

[117] Fix | Delete

#endif

[118] Fix | Delete

} isc_refcount_t;

[119] Fix | Delete

[120] Fix | Delete

#if defined(ISC_REFCOUNT_HAVESTDATOMIC)

[121] Fix | Delete

[122] Fix | Delete

#define isc_refcount_current(rp) \

[123] Fix | Delete

((unsigned int)(atomic_load_explicit(&(rp)->refs, \

[124] Fix | Delete

memory_order_acquire)))

[125] Fix | Delete

#define isc_refcount_destroy(rp) ISC_REQUIRE(isc_refcount_current(rp) == 0)

[126] Fix | Delete

[127] Fix | Delete

#define isc_refcount_increment0(rp, tp) \

[128] Fix | Delete

do { \

[129] Fix | Delete

unsigned int *_tmp = (unsigned int *)(tp); \

[130] Fix | Delete

int32_t prev; \

[131] Fix | Delete

prev = atomic_fetch_add_explicit \

[132] Fix | Delete

(&(rp)->refs, 1, memory_order_relaxed); \

[133] Fix | Delete

if (_tmp != NULL) \

[134] Fix | Delete

*_tmp = prev + 1; \

[135] Fix | Delete

} while (0)

[136] Fix | Delete

[137] Fix | Delete

#define isc_refcount_increment(rp, tp) \

[138] Fix | Delete

do { \

[139] Fix | Delete

unsigned int *_tmp = (unsigned int *)(tp); \

[140] Fix | Delete

int32_t prev; \

[141] Fix | Delete

prev = atomic_fetch_add_explicit \

[142] Fix | Delete

(&(rp)->refs, 1, memory_order_relaxed); \

[143] Fix | Delete

ISC_REQUIRE(prev > 0); \

[144] Fix | Delete

if (_tmp != NULL) \

[145] Fix | Delete

*_tmp = prev + 1; \

[146] Fix | Delete

} while (0)

[147] Fix | Delete

[148] Fix | Delete

#define isc_refcount_decrement(rp, tp) \

[149] Fix | Delete

do { \

[150] Fix | Delete

unsigned int *_tmp = (unsigned int *)(tp); \

[151] Fix | Delete

int32_t prev; \

[152] Fix | Delete

prev = atomic_fetch_sub_explicit \

[153] Fix | Delete

(&(rp)->refs, 1, memory_order_acq_rel); \

[154] Fix | Delete

ISC_REQUIRE(prev > 0); \

[155] Fix | Delete

if (_tmp != NULL) \

[156] Fix | Delete

*_tmp = prev - 1; \

[157] Fix | Delete

} while (0)

[158] Fix | Delete

[159] Fix | Delete

#else /* defined(ISC_REFCOUNT_HAVESTDATOMIC) */

[160] Fix | Delete

[161] Fix | Delete

#define isc_refcount_current(rp) \

[162] Fix | Delete

((unsigned int)(isc_atomic_xadd(&(rp)->refs, 0)))

[163] Fix | Delete

#define isc_refcount_destroy(rp) ISC_REQUIRE(isc_refcount_current(rp) == 0)

[164] Fix | Delete

[165] Fix | Delete

#define isc_refcount_increment0(rp, tp) \

[166] Fix | Delete

do { \

[167] Fix | Delete

unsigned int *_tmp = (unsigned int *)(tp); \

[168] Fix | Delete

int32_t prev; \

[169] Fix | Delete

prev = isc_atomic_xadd(&(rp)->refs, 1); \

[170] Fix | Delete

if (_tmp != NULL) \

[171] Fix | Delete

*_tmp = prev + 1; \

[172] Fix | Delete

} while (0)

[173] Fix | Delete

[174] Fix | Delete

#define isc_refcount_increment(rp, tp) \

[175] Fix | Delete

do { \

[176] Fix | Delete

unsigned int *_tmp = (unsigned int *)(tp); \

[177] Fix | Delete

int32_t prev; \

[178] Fix | Delete

prev = isc_atomic_xadd(&(rp)->refs, 1); \

[179] Fix | Delete

ISC_REQUIRE(prev > 0); \

[180] Fix | Delete

if (_tmp != NULL) \

[181] Fix | Delete

*_tmp = prev + 1; \

[182] Fix | Delete

} while (0)

[183] Fix | Delete

[184] Fix | Delete

#define isc_refcount_decrement(rp, tp) \

[185] Fix | Delete

do { \

[186] Fix | Delete

unsigned int *_tmp = (unsigned int *)(tp); \

[187] Fix | Delete

int32_t prev; \

[188] Fix | Delete

prev = isc_atomic_xadd(&(rp)->refs, -1); \

[189] Fix | Delete

ISC_REQUIRE(prev > 0); \

[190] Fix | Delete

if (_tmp != NULL) \

[191] Fix | Delete

*_tmp = prev - 1; \

[192] Fix | Delete

} while (0)

[193] Fix | Delete

[194] Fix | Delete

#endif /* defined(ISC_REFCOUNT_HAVESTDATOMIC) */

[195] Fix | Delete

[196] Fix | Delete

#else /* defined(ISC_REFCOUNT_HAVEATOMIC) */

[197] Fix | Delete

[198] Fix | Delete

typedef struct isc_refcount {

[199] Fix | Delete

int refs;

[200] Fix | Delete

isc_mutex_t lock;

[201] Fix | Delete

} isc_refcount_t;

[202] Fix | Delete

[203] Fix | Delete

/*% Destroys a reference counter. */

[204] Fix | Delete

#define isc_refcount_destroy(rp) \

[205] Fix | Delete

do { \

[206] Fix | Delete

isc_result_t _result; \

[207] Fix | Delete

ISC_REQUIRE((rp)->refs == 0); \

[208] Fix | Delete

_result = isc_mutex_destroy(&(rp)->lock); \

[209] Fix | Delete

ISC_ERROR_RUNTIMECHECK(_result == ISC_R_SUCCESS); \

[210] Fix | Delete

} while (0)

[211] Fix | Delete

[212] Fix | Delete

unsigned int isc_refcount_current(isc_refcount_t *rp);

[213] Fix | Delete

[214] Fix | Delete

/*%

[215] Fix | Delete

* Increments the reference count, returning the new value in

[216] Fix | Delete

* 'tp' if it's not NULL.

[217] Fix | Delete

*/

[218] Fix | Delete

#define isc_refcount_increment0(rp, tp) \

[219] Fix | Delete

do { \

[220] Fix | Delete

isc_result_t _result; \

[221] Fix | Delete

unsigned int *_tmp = (unsigned int *)(tp); \

[222] Fix | Delete

_result = isc_mutex_lock(&(rp)->lock); \

[223] Fix | Delete

ISC_ERROR_RUNTIMECHECK(_result == ISC_R_SUCCESS); \

[224] Fix | Delete

++((rp)->refs); \

[225] Fix | Delete

if (_tmp != NULL) \

[226] Fix | Delete

*_tmp = ((rp)->refs); \

[227] Fix | Delete

_result = isc_mutex_unlock(&(rp)->lock); \

[228] Fix | Delete

ISC_ERROR_RUNTIMECHECK(_result == ISC_R_SUCCESS); \

[229] Fix | Delete

} while (0)

[230] Fix | Delete

[231] Fix | Delete

#define isc_refcount_increment(rp, tp) \

[232] Fix | Delete

do { \

[233] Fix | Delete

isc_result_t _result; \

[234] Fix | Delete

unsigned int *_tmp = (unsigned int *)(tp); \

[235] Fix | Delete

_result = isc_mutex_lock(&(rp)->lock); \

[236] Fix | Delete

ISC_ERROR_RUNTIMECHECK(_result == ISC_R_SUCCESS); \

[237] Fix | Delete

ISC_REQUIRE((rp)->refs > 0); \

[238] Fix | Delete

++((rp)->refs); \

[239] Fix | Delete

if (_tmp != NULL) \

[240] Fix | Delete

*_tmp = ((rp)->refs); \

[241] Fix | Delete

_result = isc_mutex_unlock(&(rp)->lock); \

[242] Fix | Delete

ISC_ERROR_RUNTIMECHECK(_result == ISC_R_SUCCESS); \

[243] Fix | Delete

} while (0)

[244] Fix | Delete

[245] Fix | Delete

/*%

[246] Fix | Delete

* Decrements the reference count, returning the new value in 'tp'

[247] Fix | Delete

* if it's not NULL.

[248] Fix | Delete

*/

[249] Fix | Delete

#define isc_refcount_decrement(rp, tp) \

[250] Fix | Delete

do { \

[251] Fix | Delete

isc_result_t _result; \

[252] Fix | Delete

unsigned int *_tmp = (unsigned int *)(tp); \

[253] Fix | Delete

_result = isc_mutex_lock(&(rp)->lock); \

[254] Fix | Delete

ISC_ERROR_RUNTIMECHECK(_result == ISC_R_SUCCESS); \

[255] Fix | Delete

ISC_REQUIRE((rp)->refs > 0); \

[256] Fix | Delete

--((rp)->refs); \

[257] Fix | Delete

if (_tmp != NULL) \

[258] Fix | Delete

*_tmp = ((rp)->refs); \

[259] Fix | Delete

_result = isc_mutex_unlock(&(rp)->lock); \

[260] Fix | Delete

ISC_ERROR_RUNTIMECHECK(_result == ISC_R_SUCCESS); \

[261] Fix | Delete

} while (0)

[262] Fix | Delete

[263] Fix | Delete

#endif /* defined(ISC_REFCOUNT_ATOMIC) */

[264] Fix | Delete

[265] Fix | Delete

#else /* ISC_PLATFORM_USETHREADS */

[266] Fix | Delete

[267] Fix | Delete

typedef struct isc_refcount {

[268] Fix | Delete

int refs;

[269] Fix | Delete

} isc_refcount_t;

[270] Fix | Delete

[271] Fix | Delete

#define isc_refcount_destroy(rp) ISC_REQUIRE((rp)->refs == 0)

[272] Fix | Delete

#define isc_refcount_current(rp) ((unsigned int)((rp)->refs))

[273] Fix | Delete

[274] Fix | Delete

#define isc_refcount_increment0(rp, tp) \

[275] Fix | Delete

do { \

[276] Fix | Delete

unsigned int *_tmp = (unsigned int *)(tp); \

[277] Fix | Delete

int _n = ++(rp)->refs; \

[278] Fix | Delete

if (_tmp != NULL) \

[279] Fix | Delete

*_tmp = _n; \

[280] Fix | Delete

} while (0)

[281] Fix | Delete

[282] Fix | Delete

#define isc_refcount_increment(rp, tp) \

[283] Fix | Delete

do { \

[284] Fix | Delete

unsigned int *_tmp = (unsigned int *)(tp); \

[285] Fix | Delete

int _n; \

[286] Fix | Delete

ISC_REQUIRE((rp)->refs > 0); \

[287] Fix | Delete

_n = ++(rp)->refs; \

[288] Fix | Delete

if (_tmp != NULL) \

[289] Fix | Delete

*_tmp = _n; \

[290] Fix | Delete

} while (0)

[291] Fix | Delete

[292] Fix | Delete

#define isc_refcount_decrement(rp, tp) \

[293] Fix | Delete

do { \

[294] Fix | Delete

unsigned int *_tmp = (unsigned int *)(tp); \

[295] Fix | Delete

int _n; \

[296] Fix | Delete

ISC_REQUIRE((rp)->refs > 0); \

[297] Fix | Delete

_n = --(rp)->refs; \

[298] Fix | Delete

if (_tmp != NULL) \

[299] Fix | Delete

*_tmp = _n; \

[300] Fix | Delete

} while (0)

[301] Fix | Delete

[302] Fix | Delete

#endif /* ISC_PLATFORM_USETHREADS */

[303] Fix | Delete

[304] Fix | Delete

isc_result_t

[305] Fix | Delete

isc_refcount_init(isc_refcount_t *ref, unsigned int n);

[306] Fix | Delete

[307] Fix | Delete

ISC_LANG_ENDDECLS

[308] Fix | Delete

[309] Fix | Delete

#endif /* ISC_REFCOUNT_H */

[310] Fix | Delete

[311] Fix | Delete