lib/compiler.h

   1 /*
   2  * Copyright (c) 2008, 2009, 2010, 2011, 2012, 2013 Nicira, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at:
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef COMPILER_H
  18 #define COMPILER_H 1
  19
  20 #ifndef __has_feature
  21   #define __has_feature(x) 0
  22 #endif
  23 #ifndef __has_extension
  24   #define __has_extension(x) 0
  25 #endif
  26
  27 #if __GNUC__ && !__CHECKER__
  28 #define NO_RETURN __attribute__((__noreturn__))
  29 #define OVS_UNUSED __attribute__((__unused__))
  30 #define PRINTF_FORMAT(FMT, ARG1) __attribute__((__format__(printf, FMT, ARG1)))
  31 #define STRFTIME_FORMAT(FMT) __attribute__((__format__(__strftime__, FMT, 0)))
  32 #define MALLOC_LIKE __attribute__((__malloc__))
  33 #define ALWAYS_INLINE __attribute__((always_inline))
  34 #define WARN_UNUSED_RESULT __attribute__((__warn_unused_result__))
  35 #define SENTINEL(N) __attribute__((sentinel(N)))
  36 #define OVS_LIKELY(CONDITION) __builtin_expect(!!(CONDITION), 1)
  37 #define OVS_UNLIKELY(CONDITION) __builtin_expect(!!(CONDITION), 0)
  38 #else
  39 #define NO_RETURN
  40 #define OVS_UNUSED
  41 #define PRINTF_FORMAT(FMT, ARG1)
  42 #define STRFTIME_FORMAT(FMT)
  43 #define MALLOC_LIKE
  44 #define ALWAYS_INLINE
  45 #define WARN_UNUSED_RESULT
  46 #define SENTINEL(N)
  47 #define OVS_LIKELY(CONDITION) (!!(CONDITION))
  48 #define OVS_UNLIKELY(CONDITION) (!!(CONDITION))
  49 #endif
  50
  51 #if __has_feature(c_thread_safety_attributes)
  52 /* "clang" annotations for thread safety check.
  53  *
  54  * OVS_LOCKABLE indicates that the struct contains mutex element
  55  * which can be locked by functions like ovs_mutex_lock().
  56  *
  57  * Below, the word MUTEX stands for the name of an object with an OVS_LOCKABLE
  58  * struct type.  It can also be a comma-separated list of multiple structs,
  59  * e.g. to require a function to hold multiple locks while invoked.
  60  *
  61  *
  62  * On a variable:
  63  *
  64  *    - OVS_GUARDED indicates that the variable may only be accessed some mutex
  65  *      is held.
  66  *
  67  *    - OVS_GUARDED_BY(MUTEX) indicates that the variable may only be accessed
  68  *      while the specific MUTEX is held.
  69  *
  70  *
  71  * On a variable A of mutex type:
  72  *
  73  *    - OVS_ACQ_BEFORE(B), where B is a mutex or a comma-separated list of
  74  *      mutexes, declare that if both A and B are acquired at the same time,
  75  *      then A must be acquired before B.  That is, B nests inside A.
  76  *
  77  *    - OVS_ACQ_AFTER(B) is the opposite of OVS_ACQ_BEFORE(B), that is, it
  78  *      declares that A nests inside B.
  79  *
  80  *
  81  * On a function, the following attributes apply to mutexes:
  82  *
  83  *    - OVS_ACQUIRES(MUTEX) indicate that the function must be called without
  84  *      holding MUTEX and that it returns holding MUTEX.
  85  *
  86  *    - OVS_RELEASES(MUTEX) indicates that the function may only be called with
  87  *      MUTEX held and that it returns with MUTEX released.  It can be used for
  88  *      all types of MUTEX.
  89  *
  90  *    - OVS_TRY_LOCK(RETVAL, MUTEX) indicate that the function will try to
  91  *      acquire MUTEX.  RETVAL is an integer or boolean value specifying the
  92  *      return value of a successful lock acquisition.
  93  *
  94  *    - OVS_REQUIRES(MUTEX) indicate that the function may only be called with
  95  *      MUTEX held and that the function does not release MUTEX.
  96  *
  97  *    - OVS_LOCKS_EXCLUDED(MUTEX) indicates that the function may only be
  98  *      called when MUTEX is not held.
  99  *
 100  *
 101  * The following variants, with the same syntax, apply to reader-writer locks:
 102  *
 103  *    mutex                rwlock, for reading  rwlock, for writing
 104  *    -------------------  -------------------  -------------------
 105  *    OVS_ACQUIRES         OVS_ACQ_RDLOCK       OVS_ACQ_WRLOCK
 106  *    OVS_RELEASES         OVS_RELEASES         OVS_RELEASES
 107  *    OVS_TRY_LOCK         OVS_TRY_RDLOCK       OVS_TRY_WRLOCK
 108  *    OVS_REQUIRES         OVS_REQ_RDLOCK       OVS_REQ_WRLOCK
 109  *    OVS_LOCKS_EXCLUDED   OVS_LOCKS_EXCLUDED   OVS_LOCKS_EXCLUDED
 110  */
 111 #define OVS_LOCKABLE __attribute__((lockable))
 112 #define OVS_REQ_RDLOCK(...) __attribute__((shared_locks_required(__VA_ARGS__)))
 113 #define OVS_ACQ_RDLOCK(...) __attribute__((shared_lock_function(__VA_ARGS__)))
 114 #define OVS_REQ_WRLOCK(...) \
 115     __attribute__((exclusive_locks_required(__VA_ARGS__)))
 116 #define OVS_ACQ_WRLOCK(...) \
 117     __attribute__((exclusive_lock_function(__VA_ARGS__)))
 118 #define OVS_REQUIRES(...) \
 119     __attribute__((exclusive_locks_required(__VA_ARGS__)))
 120 #define OVS_ACQUIRES(...) \
 121     __attribute__((exclusive_lock_function(__VA_ARGS__)))
 122 #define OVS_TRY_WRLOCK(RETVAL, ...)                              \
 123     __attribute__((exclusive_trylock_function(RETVAL, __VA_ARGS__)))
 124 #define OVS_TRY_RDLOCK(RETVAL, ...)                          \
 125     __attribute__((shared_trylock_function(RETVAL, __VA_ARGS__)))
 126 #define OVS_TRY_LOCK(RETVAL, ...)                                \
 127     __attribute__((exclusive_trylock_function(RETVAL, __VA_ARGS__)))
 128 #define OVS_GUARDED __attribute__((guarded_var))
 129 #define OVS_GUARDED_BY(...) __attribute__((guarded_by(__VA_ARGS__)))
 130 #define OVS_RELEASES(...) __attribute__((unlock_function(__VA_ARGS__)))
 131 #define OVS_EXCLUDED(...) __attribute__((locks_excluded(__VA_ARGS__)))
 132 #define OVS_ACQ_BEFORE(...) __attribute__((acquired_before(__VA_ARGS__)))
 133 #define OVS_ACQ_AFTER(...) __attribute__((acquired_after(__VA_ARGS__)))
 134 #define OVS_NO_THREAD_SAFETY_ANALYSIS \
 135     __attribute__((no_thread_safety_analysis))
 136 #else  /* not Clang */
 137 #define OVS_LOCKABLE
 138 #define OVS_REQ_RDLOCK(...)
 139 #define OVS_ACQ_RDLOCK(...)
 140 #define OVS_REQ_WRLOCK(...)
 141 #define OVS_ACQ_WRLOCK(...)
 142 #define OVS_REQUIRES(...)
 143 #define OVS_ACQUIRES(...)
 144 #define OVS_TRY_WRLOCK(...)
 145 #define OVS_TRY_RDLOCK(...)
 146 #define OVS_TRY_LOCK(...)
 147 #define OVS_GUARDED
 148 #define OVS_GUARDED_BY(...)
 149 #define OVS_EXCLUDED(...)
 150 #define OVS_RELEASES(...)
 151 #define OVS_ACQ_BEFORE(...)
 152 #define OVS_ACQ_AFTER(...)
 153 #define OVS_NO_THREAD_SAFETY_ANALYSIS
 154 #endif
 155
 156 /* ISO C says that a C implementation may choose any integer type for an enum
 157  * that is sufficient to hold all of its values.  Common ABIs (such as the
 158  * System V ABI used on i386 GNU/Linux) always use a full-sized "int", even
 159  * when a smaller type would suffice.
 160  *
 161  * In GNU C, "enum __attribute__((packed)) name { ... }" defines 'name' as an
 162  * enum compatible with a type that is no bigger than necessary.  This is the
 163  * intended use of OVS_PACKED_ENUM.
 164  *
 165  * OVS_PACKED_ENUM is intended for use only as a space optimization, since it
 166  * only works with GCC.  That means that it must not be used in wire protocols
 167  * or otherwise exposed outside of a single process. */
 168 #if __GNUC__ && !__CHECKER__
 169 #define OVS_PACKED_ENUM __attribute__((__packed__))
 170 #else
 171 #define OVS_PACKED_ENUM
 172 #endif
 173
 174 #ifndef _MSC_VER
 175 #define OVS_PACKED(DECL) DECL __attribute__((__packed__))
 176 #else
 177 #define OVS_PACKED(DECL) __pragma(pack(push, 1)) DECL __pragma(pack(pop))
 178 #endif
 179
 180 #endif /* compiler.h */