contrib/bind-9.2.4rc7/lib/isc/include/isc/util.h

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1998-2001  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and 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: util.h,v 1.21.2.1 2004/03/09 06:12:03 marka Exp $ */
  19
  20 #ifndef ISC_UTIL_H
  21 #define ISC_UTIL_H 1
  22
  23 /*
  24  * NOTE:
  25  *
  26  * This file is not to be included from any <isc/???.h> (or other) library
  27  * files.
  28  *
  29  * Including this file puts several macros in your name space that are
  30  * not protected (as all the other ISC functions/macros do) by prepending
  31  * ISC_ or isc_ to the name.
  32  */
  33
  34 /***
  35  *** General Macros.
  36  ***/
  37
  38 /*
  39  * Use this to hide unused function arguments.
  40  *
  41  * int
  42  * foo(char *bar)
  43  * {
  44  *      UNUSED(bar);
  45  * }
  46  */
  47 #define UNUSED(x)      (void)(x)
  48
  49 #define ISC_MAX(a, b)  ((a) > (b) ? (a) : (b))
  50 #define ISC_MIN(a, b)  ((a) < (b) ? (a) : (b))
  51
  52 /*
  53  * Use this to remove the const qualifier of a variable to assign it to
  54  * a non-const variable or pass it as a non-const function argument ...
  55  * but only when you are sure it won't then be changed!
  56  * This is necessary to sometimes shut up some compilers
  57  * (as with gcc -Wcast-qual) when there is just no other good way to avoid the
  58  * situation.
  59  */
  60 #define DE_CONST(konst, var) \
  61         do { \
  62                 union { const void *k; void *v; } _u; \
  63                 _u.k = konst; \
  64                 var = _u.v; \
  65         } while (0)
  66
  67 /*
  68  * We use macros instead of calling the routines directly because
  69  * the capital letters make the locking stand out.
  70  *
  71  * We RUNTIME_CHECK for success since in general there's no way
  72  * for us to continue if they fail.
  73  */
  74
  75 #ifdef ISC_UTIL_TRACEON
  76 #define ISC_UTIL_TRACE(a) a
  77 #include <stdio.h>              /* Required for fprintf/stderr when tracing. */
  78 #include <isc/msgs.h>           /* Required for isc_msgcat when tracing. */
  79 #else
  80 #define ISC_UTIL_TRACE(a)
  81 #endif
  82
  83 #include <isc/result.h>         /* Contractual promise. */
  84
  85 #define LOCK(lp) do { \
  86         ISC_UTIL_TRACE(fprintf(stderr, "%s %p %s %d\n", \
  87                                isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \
  88                                               ISC_MSG_LOCKING, "LOCKING"), \
  89                                (lp), __FILE__, __LINE__)); \
  90         RUNTIME_CHECK(isc_mutex_lock((lp)) == ISC_R_SUCCESS); \
  91         ISC_UTIL_TRACE(fprintf(stderr, "%s %p %s %d\n", \
  92                                isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \
  93                                               ISC_MSG_LOCKED, "LOCKED"), \
  94                                (lp), __FILE__, __LINE__)); \
  95         } while (0)
  96 #define UNLOCK(lp) do { \
  97         RUNTIME_CHECK(isc_mutex_unlock((lp)) == ISC_R_SUCCESS); \
  98         ISC_UTIL_TRACE(fprintf(stderr, "%s %p %s %d\n", \
  99                                isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \
 100                                               ISC_MSG_UNLOCKED, "UNLOCKED"), \
 101                                (lp), __FILE__, __LINE__)); \
 102         } while (0)
 103 #define ISLOCKED(lp) (1)
 104 #define DESTROYLOCK(lp) \
 105         RUNTIME_CHECK(isc_mutex_destroy((lp)) == ISC_R_SUCCESS)
 106
 107
 108 #define BROADCAST(cvp) do { \
 109         ISC_UTIL_TRACE(fprintf(stderr, "%s %p %s %d\n", \
 110                                isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \
 111                                               ISC_MSG_BROADCAST, "BROADCAST"),\
 112                                (cvp), __FILE__, __LINE__)); \
 113         RUNTIME_CHECK(isc_condition_broadcast((cvp)) == ISC_R_SUCCESS); \
 114         } while (0)
 115 #define SIGNAL(cvp) do { \
 116         ISC_UTIL_TRACE(fprintf(stderr, "%s %p %s %d\n", \
 117                                isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \
 118                                               ISC_MSG_SIGNAL, "SIGNAL"), \
 119                                (cvp), __FILE__, __LINE__)); \
 120         RUNTIME_CHECK(isc_condition_signal((cvp)) == ISC_R_SUCCESS); \
 121         } while (0)
 122 #define WAIT(cvp, lp) do { \
 123         ISC_UTIL_TRACE(fprintf(stderr, "%s %p %s %p %s %d\n", \
 124                                isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \
 125                                               ISC_MSG_UTILWAIT, "WAIT"), \
 126                                (cvp), \
 127                                isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \
 128                                               ISC_MSG_LOCK, "LOCK"), \
 129                                (lp), __FILE__, __LINE__)); \
 130         RUNTIME_CHECK(isc_condition_wait((cvp), (lp)) == ISC_R_SUCCESS); \
 131         ISC_UTIL_TRACE(fprintf(stderr, "%s %p %s %p %s %d\n", \
 132                                isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \
 133                                               ISC_MSG_WAITED, "WAITED"), \
 134                                (cvp), \
 135                                isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \
 136                                               ISC_MSG_LOCKED, "LOCKED"), \
 137                                (lp), __FILE__, __LINE__)); \
 138         } while (0)
 139
 140 /*
 141  * isc_condition_waituntil can return ISC_R_TIMEDOUT, so we
 142  * don't RUNTIME_CHECK the result.
 143  *
 144  *  XXX Also, can't really debug this then...
 145  */
 146
 147 #define WAITUNTIL(cvp, lp, tp) \
 148         isc_condition_waituntil((cvp), (lp), (tp))
 149
 150 #define RWLOCK(lp, t) do { \
 151         ISC_UTIL_TRACE(fprintf(stderr, "%s %p, %d %s %d\n", \
 152                                isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \
 153                                               ISC_MSG_RWLOCK, "RWLOCK"), \
 154                                (lp), (t), __FILE__, __LINE__)); \
 155         RUNTIME_CHECK(isc_rwlock_lock((lp), (t)) == ISC_R_SUCCESS); \
 156         ISC_UTIL_TRACE(fprintf(stderr, "%s %p, %d %s %d\n", \
 157                                isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \
 158                                               ISC_MSG_RWLOCKED, "RWLOCKED"), \
 159                                (lp), (t), __FILE__, __LINE__)); \
 160         } while (0)
 161 #define RWUNLOCK(lp, t) do { \
 162         ISC_UTIL_TRACE(fprintf(stderr, "%s %p, %d %s %d\n", \
 163                                isc_msgcat_get(isc_msgcat, ISC_MSGSET_UTIL, \
 164                                               ISC_MSG_RWUNLOCK, "RWUNLOCK"), \
 165                                (lp), (t), __FILE__, __LINE__)); \
 166         RUNTIME_CHECK(isc_rwlock_unlock((lp), (t)) == ISC_R_SUCCESS); \
 167         } while (0)
 168
 169 /*
 170  * List Macros.
 171  */
 172 #include <isc/list.h>           /* Contractual promise. */
 173
 174 #define LIST(type)                      ISC_LIST(type)
 175 #define INIT_LIST(type)                 ISC_LIST_INIT(type)
 176 #define LINK(type)                      ISC_LINK(type)
 177 #define INIT_LINK(elt, link)            ISC_LINK_INIT(elt, link)
 178 #define HEAD(list)                      ISC_LIST_HEAD(list)
 179 #define TAIL(list)                      ISC_LIST_TAIL(list)
 180 #define EMPTY(list)                     ISC_LIST_EMPTY(list)
 181 #define PREV(elt, link)                 ISC_LIST_PREV(elt, link)
 182 #define NEXT(elt, link)                 ISC_LIST_NEXT(elt, link)
 183 #define APPEND(list, elt, link)         ISC_LIST_APPEND(list, elt, link)
 184 #define PREPEND(list, elt, link)        ISC_LIST_PREPEND(list, elt, link)
 185 #define UNLINK(list, elt, link)         ISC_LIST_UNLINK(list, elt, link)
 186 #define ENQUEUE(list, elt, link)        ISC_LIST_APPEND(list, elt, link)
 187 #define DEQUEUE(list, elt, link)        ISC_LIST_UNLINK(list, elt, link)
 188 #define INSERTBEFORE(li, b, e, ln)      ISC_LIST_INSERTBEFORE(li, b, e, ln)
 189 #define INSERTAFTER(li, a, e, ln)       ISC_LIST_INSERTAFTER(li, a, e, ln)
 190 #define APPENDLIST(list1, list2, link)  ISC_LIST_APPENDLIST(list1, list2, link)
 191
 192 /*
 193  * Assertions
 194  */
 195 #include <isc/assertions.h>     /* Contractual promise. */
 196
 197 #define REQUIRE(e)                      ISC_REQUIRE(e)
 198 #define ENSURE(e)                       ISC_ENSURE(e)
 199 #define INSIST(e)                       ISC_INSIST(e)
 200 #define INVARIANT(e)                    ISC_INVARIANT(e)
 201
 202 /*
 203  * Errors
 204  */
 205 #include <isc/error.h>          /* Contractual promise. */
 206
 207 #define UNEXPECTED_ERROR                isc_error_unexpected
 208 #define FATAL_ERROR                     isc_error_fatal
 209 #define RUNTIME_CHECK(cond)             ISC_ERROR_RUNTIMECHECK(cond)
 210
 211 #endif /* ISC_UTIL_H */