/*

[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

#ifndef ISC_UTIL_H

[11] Fix | Delete

#define ISC_UTIL_H 1

[12] Fix | Delete

[13] Fix | Delete

#include <inttypes.h>

[14] Fix | Delete

[15] Fix | Delete

/*! \file isc/util.h

[16] Fix | Delete

* NOTE:

[17] Fix | Delete

*

[18] Fix | Delete

* This file is not to be included from any <isc/???.h> (or other) library

[19] Fix | Delete

* files.

[20] Fix | Delete

*

[21] Fix | Delete

* \brief

[22] Fix | Delete

* Including this file puts several macros in your name space that are

[23] Fix | Delete

* not protected (as all the other ISC functions/macros do) by prepending

[24] Fix | Delete

* ISC_ or isc_ to the name.

[25] Fix | Delete

*/

[26] Fix | Delete

[27] Fix | Delete

/***

[28] Fix | Delete

*** General Macros.

[29] Fix | Delete

***/

[30] Fix | Delete

[31] Fix | Delete

/*%

[32] Fix | Delete

* Use this to hide unused function arguments.

[33] Fix | Delete

* \code

[34] Fix | Delete

* int

[35] Fix | Delete

* foo(char *bar)

[36] Fix | Delete

* {

[37] Fix | Delete

* UNUSED(bar);

[38] Fix | Delete

* }

[39] Fix | Delete

* \endcode

[40] Fix | Delete

*/

[41] Fix | Delete

#define UNUSED(x) (void)(x)

[42] Fix | Delete

[43] Fix | Delete

/*%

[44] Fix | Delete

* The opposite: silent warnings about stored values which are never read.

[45] Fix | Delete

*/

[46] Fix | Delete

#define POST(x) (void)(x)

[47] Fix | Delete

[48] Fix | Delete

#define ISC_MAX(a, b) ((a) > (b) ? (a) : (b))

[49] Fix | Delete

#define ISC_MIN(a, b) ((a) < (b) ? (a) : (b))

[50] Fix | Delete

[51] Fix | Delete

#define ISC_CLAMP(v, x, y) ((v) < (x) ? (x) : ((v) > (y) ? (y) : (v)))

[52] Fix | Delete

[53] Fix | Delete

/*%

[54] Fix | Delete

* Use this to remove the const qualifier of a variable to assign it to

[55] Fix | Delete

* a non-const variable or pass it as a non-const function argument ...

[56] Fix | Delete

* but only when you are sure it won't then be changed!

[57] Fix | Delete

* This is necessary to sometimes shut up some compilers

[58] Fix | Delete

* (as with gcc -Wcast-qual) when there is just no other good way to avoid the

[59] Fix | Delete

* situation.

[60] Fix | Delete

*/

[61] Fix | Delete

#define DE_CONST(konst, var) \

[62] Fix | Delete

do { \

[63] Fix | Delete

union { const void *k; void *v; } _u; \

[64] Fix | Delete

_u.k = konst; \

[65] Fix | Delete

var = _u.v; \

[66] Fix | Delete

} while (0)

[67] Fix | Delete

[68] Fix | Delete

#define ARRAY_SIZE(x) (sizeof(x) / sizeof(x[0]))

[69] Fix | Delete

[70] Fix | Delete

/*%

[71] Fix | Delete

* Use this in translation units that would otherwise be empty, to

[72] Fix | Delete

* suppress compiler warnings.

[73] Fix | Delete

*/

[74] Fix | Delete

#define EMPTY_TRANSLATION_UNIT extern int isc__empty;

[75] Fix | Delete

[76] Fix | Delete

/*%

[77] Fix | Delete

* We use macros instead of calling the routines directly because

[78] Fix | Delete

* the capital letters make the locking stand out.

[79] Fix | Delete

* We RUNTIME_CHECK for success since in general there's no way

[80] Fix | Delete

* for us to continue if they fail.

[81] Fix | Delete

*/

[82] Fix | Delete

[83] Fix | Delete

#ifdef ISC_UTIL_TRACEON

[84] Fix | Delete

#define ISC_UTIL_TRACE(a) a

[85] Fix | Delete

#include <stdio.h> /* Required for fprintf/stderr when tracing. */

[86] Fix | Delete

#include <isc/msgs.h> /* Required for isc_msgcat when tracing. */

[87] Fix | Delete

#else

[88] Fix | Delete

#define ISC_UTIL_TRACE(a)

[89] Fix | Delete

#endif

[90] Fix | Delete

[91] Fix | Delete

#include <isc/result.h> /* Contractual promise. */

[92] Fix | Delete

[93] Fix | Delete

#define LOCK(lp) do { \

[94] Fix | Delete

ISC_UTIL_TRACE(fprintf(stderr, "%s %p %s %d\n", \

[95] Fix | Delete

isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \

[96] Fix | Delete

ISC_MSG_LOCKING, "LOCKING"), \

[97] Fix | Delete

(lp), __FILE__, __LINE__)); \

[98] Fix | Delete

RUNTIME_CHECK(isc_mutex_lock((lp)) == ISC_R_SUCCESS); \

[99] Fix | Delete

ISC_UTIL_TRACE(fprintf(stderr, "%s %p %s %d\n", \

[100] Fix | Delete

isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \

[101] Fix | Delete

ISC_MSG_LOCKED, "LOCKED"), \

[102] Fix | Delete

(lp), __FILE__, __LINE__)); \

[103] Fix | Delete

} while (0)

[104] Fix | Delete

#define UNLOCK(lp) do { \

[105] Fix | Delete

RUNTIME_CHECK(isc_mutex_unlock((lp)) == ISC_R_SUCCESS); \

[106] Fix | Delete

ISC_UTIL_TRACE(fprintf(stderr, "%s %p %s %d\n", \

[107] Fix | Delete

isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \

[108] Fix | Delete

ISC_MSG_UNLOCKED, "UNLOCKED"), \

[109] Fix | Delete

(lp), __FILE__, __LINE__)); \

[110] Fix | Delete

} while (0)

[111] Fix | Delete

#define DESTROYLOCK(lp) \

[112] Fix | Delete

RUNTIME_CHECK(isc_mutex_destroy((lp)) == ISC_R_SUCCESS)

[113] Fix | Delete

[114] Fix | Delete

[115] Fix | Delete

#define BROADCAST(cvp) do { \

[116] Fix | Delete

ISC_UTIL_TRACE(fprintf(stderr, "%s %p %s %d\n", \

[117] Fix | Delete

isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \

[118] Fix | Delete

ISC_MSG_BROADCAST, "BROADCAST"),\

[119] Fix | Delete

(cvp), __FILE__, __LINE__)); \

[120] Fix | Delete

RUNTIME_CHECK(isc_condition_broadcast((cvp)) == ISC_R_SUCCESS); \

[121] Fix | Delete

} while (0)

[122] Fix | Delete

#define SIGNAL(cvp) do { \

[123] Fix | Delete

ISC_UTIL_TRACE(fprintf(stderr, "%s %p %s %d\n", \

[124] Fix | Delete

isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \

[125] Fix | Delete

ISC_MSG_SIGNAL, "SIGNAL"), \

[126] Fix | Delete

(cvp), __FILE__, __LINE__)); \

[127] Fix | Delete

RUNTIME_CHECK(isc_condition_signal((cvp)) == ISC_R_SUCCESS); \

[128] Fix | Delete

} while (0)

[129] Fix | Delete

#define WAIT(cvp, lp) do { \

[130] Fix | Delete

ISC_UTIL_TRACE(fprintf(stderr, "%s %p %s %p %s %d\n", \

[131] Fix | Delete

isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \

[132] Fix | Delete

ISC_MSG_UTILWAIT, "WAIT"), \

[133] Fix | Delete

(cvp), \

[134] Fix | Delete

isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \

[135] Fix | Delete

ISC_MSG_LOCK, "LOCK"), \

[136] Fix | Delete

(lp), __FILE__, __LINE__)); \

[137] Fix | Delete

RUNTIME_CHECK(isc_condition_wait((cvp), (lp)) == ISC_R_SUCCESS); \

[138] Fix | Delete

ISC_UTIL_TRACE(fprintf(stderr, "%s %p %s %p %s %d\n", \

[139] Fix | Delete

isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \

[140] Fix | Delete

ISC_MSG_WAITED, "WAITED"), \

[141] Fix | Delete

(cvp), \

[142] Fix | Delete

isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \

[143] Fix | Delete

ISC_MSG_LOCKED, "LOCKED"), \

[144] Fix | Delete

(lp), __FILE__, __LINE__)); \

[145] Fix | Delete

} while (0)

[146] Fix | Delete

[147] Fix | Delete

/*

[148] Fix | Delete

* isc_condition_waituntil can return ISC_R_TIMEDOUT, so we

[149] Fix | Delete

* don't RUNTIME_CHECK the result.

[150] Fix | Delete

*

[151] Fix | Delete

* XXX Also, can't really debug this then...

[152] Fix | Delete

*/

[153] Fix | Delete

[154] Fix | Delete

#define WAITUNTIL(cvp, lp, tp) \

[155] Fix | Delete

isc_condition_waituntil((cvp), (lp), (tp))

[156] Fix | Delete

[157] Fix | Delete

#define RWLOCK(lp, t) do { \

[158] Fix | Delete

ISC_UTIL_TRACE(fprintf(stderr, "%s %p, %d %s %d\n", \

[159] Fix | Delete

isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \

[160] Fix | Delete

ISC_MSG_RWLOCK, "RWLOCK"), \

[161] Fix | Delete

(lp), (t), __FILE__, __LINE__)); \

[162] Fix | Delete

RUNTIME_CHECK(isc_rwlock_lock((lp), (t)) == ISC_R_SUCCESS); \

[163] Fix | Delete

ISC_UTIL_TRACE(fprintf(stderr, "%s %p, %d %s %d\n", \

[164] Fix | Delete

isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \

[165] Fix | Delete

ISC_MSG_RWLOCKED, "RWLOCKED"), \

[166] Fix | Delete

(lp), (t), __FILE__, __LINE__)); \

[167] Fix | Delete

} while (0)

[168] Fix | Delete

#define RWUNLOCK(lp, t) do { \

[169] Fix | Delete

ISC_UTIL_TRACE(fprintf(stderr, "%s %p, %d %s %d\n", \

[170] Fix | Delete

isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \

[171] Fix | Delete

ISC_MSG_RWUNLOCK, "RWUNLOCK"), \

[172] Fix | Delete

(lp), (t), __FILE__, __LINE__)); \

[173] Fix | Delete

RUNTIME_CHECK(isc_rwlock_unlock((lp), (t)) == ISC_R_SUCCESS); \

[174] Fix | Delete

} while (0)

[175] Fix | Delete

[176] Fix | Delete

#define DESTROYMUTEXBLOCK(bp, n) \

[177] Fix | Delete

RUNTIME_CHECK(isc_mutexblock_destroy((bp), (n)) == ISC_R_SUCCESS)

[178] Fix | Delete

[179] Fix | Delete

/*

[180] Fix | Delete

* List Macros.

[181] Fix | Delete

*/

[182] Fix | Delete

#include <isc/list.h> /* Contractual promise. */

[183] Fix | Delete

[184] Fix | Delete

#define LIST(type) ISC_LIST(type)

[185] Fix | Delete

#define INIT_LIST(type) ISC_LIST_INIT(type)

[186] Fix | Delete

#define LINK(type) ISC_LINK(type)

[187] Fix | Delete

#define INIT_LINK(elt, link) ISC_LINK_INIT(elt, link)

[188] Fix | Delete

#define HEAD(list) ISC_LIST_HEAD(list)

[189] Fix | Delete

#define TAIL(list) ISC_LIST_TAIL(list)

[190] Fix | Delete

#define EMPTY(list) ISC_LIST_EMPTY(list)

[191] Fix | Delete

#define PREV(elt, link) ISC_LIST_PREV(elt, link)

[192] Fix | Delete

#define NEXT(elt, link) ISC_LIST_NEXT(elt, link)

[193] Fix | Delete

#define APPEND(list, elt, link) ISC_LIST_APPEND(list, elt, link)

[194] Fix | Delete

#define PREPEND(list, elt, link) ISC_LIST_PREPEND(list, elt, link)

[195] Fix | Delete

#define UNLINK(list, elt, link) ISC_LIST_UNLINK(list, elt, link)

[196] Fix | Delete

#define ENQUEUE(list, elt, link) ISC_LIST_APPEND(list, elt, link)

[197] Fix | Delete

#define DEQUEUE(list, elt, link) ISC_LIST_UNLINK(list, elt, link)

[198] Fix | Delete

#define INSERTBEFORE(li, b, e, ln) ISC_LIST_INSERTBEFORE(li, b, e, ln)

[199] Fix | Delete

#define INSERTAFTER(li, a, e, ln) ISC_LIST_INSERTAFTER(li, a, e, ln)

[200] Fix | Delete

#define APPENDLIST(list1, list2, link) ISC_LIST_APPENDLIST(list1, list2, link)

[201] Fix | Delete

[202] Fix | Delete

/*%

[203] Fix | Delete

* Performance

[204] Fix | Delete

*/

[205] Fix | Delete

#include <isc/likely.h>

[206] Fix | Delete

[207] Fix | Delete

#ifdef HAVE_BUILTIN_UNREACHABLE

[208] Fix | Delete

#define ISC_UNREACHABLE() __builtin_unreachable();

[209] Fix | Delete

#else

[210] Fix | Delete

#define ISC_UNREACHABLE()

[211] Fix | Delete

#endif

[212] Fix | Delete

[213] Fix | Delete

#if !defined(__has_feature)

[214] Fix | Delete

#define __has_feature(x) 0

[215] Fix | Delete

#endif

[216] Fix | Delete

[217] Fix | Delete

/* GCC defines __SANITIZE_ADDRESS__, so reuse the macro for clang */

[218] Fix | Delete

#if __has_feature(address_sanitizer)

[219] Fix | Delete

#define __SANITIZE_ADDRESS__ 1

[220] Fix | Delete

#endif

[221] Fix | Delete

[222] Fix | Delete

/* GCC defines __SANITIZE_THREAD__, so reuse the macro for clang */

[223] Fix | Delete

#if __has_feature(thread_sanitizer)

[224] Fix | Delete

#define __SANITIZE_THREAD__ 1

[225] Fix | Delete

#endif

[226] Fix | Delete

[227] Fix | Delete

#if __SANITIZE_THREAD__

[228] Fix | Delete

#define ISC_NO_SANITIZE_THREAD __attribute__((no_sanitize("thread"))) __attribute__((noinline))

[229] Fix | Delete

#define ISC_NO_SANITIZE_INLINE

[230] Fix | Delete

#else /* if __SANITIZE_THREAD__ */

[231] Fix | Delete

#define ISC_NO_SANITIZE_THREAD

[232] Fix | Delete

#define ISC_NO_SANITIZE_INLINE inline

[233] Fix | Delete

#endif /* if __SANITIZE_THREAD__ */

[234] Fix | Delete

[235] Fix | Delete

#ifdef UNIT_TESTING

[236] Fix | Delete

extern void mock_assert(const int result, const char* const expression,

[237] Fix | Delete

const char * const file, const int line);

[238] Fix | Delete

/*

[239] Fix | Delete

* Allow clang to determine that the following code is not reached

[240] Fix | Delete

* by calling abort() if the condition fails. The abort() will

[241] Fix | Delete

* never be executed as mock_assert() and _assert_true() longjmp

[242] Fix | Delete

* or exit if the condition is false.

[243] Fix | Delete

*/

[244] Fix | Delete

#define REQUIRE(expression) \

[245] Fix | Delete

((!(expression)) ? \

[246] Fix | Delete

(mock_assert(0, #expression, __FILE__, __LINE__), abort()) : (void)0)

[247] Fix | Delete

#define ENSURE(expression) \

[248] Fix | Delete

((!(int)(expression)) ? \

[249] Fix | Delete

(mock_assert(0, #expression, __FILE__, __LINE__), abort()) : (void)0)

[250] Fix | Delete

#define INSIST(expression) \

[251] Fix | Delete

((!(expression)) ? \

[252] Fix | Delete

(mock_assert(0, #expression, __FILE__, __LINE__), abort()) : (void)0)

[253] Fix | Delete

#define INVARIANT(expression) \

[254] Fix | Delete

((!(expression)) ? \

[255] Fix | Delete

(mock_assert(0, #expression, __FILE__, __LINE__), abort()) : (void)0)

[256] Fix | Delete

#define _assert_true(c, e, f, l) \

[257] Fix | Delete

((c) ? (void)0 : (_assert_true(0, e, f, l), abort()))

[258] Fix | Delete

#define _assert_int_equal(a, b, f, l) \

[259] Fix | Delete

(((a) == (b)) ? (void)0 : (_assert_int_equal(a, b, f, l), abort()))

[260] Fix | Delete

#define _assert_int_not_equal(a, b, f, l) \

[261] Fix | Delete

(((a) != (b)) ? (void)0 : (_assert_int_not_equal(a, b, f, l), abort()))

[262] Fix | Delete

#else /* UNIT_TESTING */

[263] Fix | Delete

[264] Fix | Delete

#ifndef CPPCHECK

[265] Fix | Delete

[266] Fix | Delete

/*

[267] Fix | Delete

* Assertions

[268] Fix | Delete

*/

[269] Fix | Delete

#include <isc/assertions.h> /* Contractual promise. */

[270] Fix | Delete

[271] Fix | Delete

/*% Require Assertion */

[272] Fix | Delete

#define REQUIRE(e) ISC_REQUIRE(e)

[273] Fix | Delete

/*% Ensure Assertion */

[274] Fix | Delete

#define ENSURE(e) ISC_ENSURE(e)

[275] Fix | Delete

/*% Insist Assertion */

[276] Fix | Delete

#define INSIST(e) ISC_INSIST(e)

[277] Fix | Delete

/*% Invariant Assertion */

[278] Fix | Delete

#define INVARIANT(e) ISC_INVARIANT(e)

[279] Fix | Delete

[280] Fix | Delete

#else /* CPPCHECK */

[281] Fix | Delete

[282] Fix | Delete

/*% Require Assertion */

[283] Fix | Delete

#define REQUIRE(e) if (!(e)) abort()

[284] Fix | Delete

/*% Ensure Assertion */

[285] Fix | Delete

#define ENSURE(e) if (!(e)) abort()

[286] Fix | Delete

/*% Insist Assertion */

[287] Fix | Delete

#define INSIST(e) if (!(e)) abort()

[288] Fix | Delete

/*% Invariant Assertion */

[289] Fix | Delete

#define INVARIANT(e) if (!(e)) abort()

[290] Fix | Delete

[291] Fix | Delete

#endif /* CPPCHECK */

[292] Fix | Delete

[293] Fix | Delete

#endif /* UNIT_TESTING */

[294] Fix | Delete

[295] Fix | Delete

/*

[296] Fix | Delete

* Errors

[297] Fix | Delete

*/

[298] Fix | Delete

#include <isc/error.h> /* Contractual promise. */

[299] Fix | Delete

[300] Fix | Delete

/*% Unexpected Error */

[301] Fix | Delete

#define UNEXPECTED_ERROR isc_error_unexpected

[302] Fix | Delete

/*% Fatal Error */

[303] Fix | Delete

#define FATAL_ERROR isc_error_fatal

[304] Fix | Delete

[305] Fix | Delete

#ifdef UNIT_TESTING

[306] Fix | Delete

[307] Fix | Delete

#define RUNTIME_CHECK(expression) \

[308] Fix | Delete

((!(expression)) ? \

[309] Fix | Delete

(mock_assert(0, #expression, __FILE__, __LINE__), abort()) : (void)0)

[310] Fix | Delete

[311] Fix | Delete

#else /* UNIT_TESTING */

[312] Fix | Delete

[313] Fix | Delete

#ifndef CPPCHECK

[314] Fix | Delete

/*% Runtime Check */

[315] Fix | Delete

#define RUNTIME_CHECK(cond) ISC_ERROR_RUNTIMECHECK(cond)

[316] Fix | Delete

#else

[317] Fix | Delete

#define RUNTIME_CHECK(e) if (!(e)) abort()

[318] Fix | Delete

#endif

[319] Fix | Delete

[320] Fix | Delete

#endif /* UNIT_TESTING */

[321] Fix | Delete

[322] Fix | Delete

/*%

[323] Fix | Delete

* Time

[324] Fix | Delete

*/

[325] Fix | Delete

#define TIME_NOW(tp) RUNTIME_CHECK(isc_time_now((tp)) == ISC_R_SUCCESS)

[326] Fix | Delete

#ifdef CLOCK_BOOTTIME

[327] Fix | Delete

#define TIME_MONOTONIC(tp) RUNTIME_CHECK(isc_time_boottime((tp)) == ISC_R_SUCCESS)

[328] Fix | Delete

#endif

[329] Fix | Delete

[330] Fix | Delete

[331] Fix | Delete

/*%

[332] Fix | Delete

* Alignment

[333] Fix | Delete

*/

[334] Fix | Delete

#ifdef __GNUC__

[335] Fix | Delete

#define ISC_ALIGN(x, a) (((x) + (a) - 1) & ~((typeof(x))(a) - 1))

[336] Fix | Delete

#else

[337] Fix | Delete

#define ISC_ALIGN(x, a) (((x) + (a) - 1) & ~((uintmax_t)(a) - 1))

[338] Fix | Delete

#endif

[339] Fix | Delete

[340] Fix | Delete

/*%

[341] Fix | Delete

* Misc

[342] Fix | Delete

*/

[343] Fix | Delete

#include <isc/deprecated.h>

[344] Fix | Delete

[345] Fix | Delete

#endif /* ISC_UTIL_H */

[346] Fix | Delete

[347] Fix | Delete