1 /*
2 * Copyright (C) 2015 The Android Open Source Project
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 ANDROID_BASE_MACROS_H
18 #define ANDROID_BASE_MACROS_H
19
20 #include <stddef.h> // for size_t
21 #include <unistd.h> // for TEMP_FAILURE_RETRY
22
23 // bionic and glibc both have TEMP_FAILURE_RETRY, but eg Mac OS' libc doesn't.
24 #ifndef TEMP_FAILURE_RETRY
25 #define TEMP_FAILURE_RETRY(exp) \
26 ({ \
27 decltype(exp) _rc; \
28 do { \
29 _rc = (exp); \
30 } while (_rc == -1 && errno == EINTR); \
31 _rc; \
32 })
33 #endif
34
35 // A macro to disallow the copy constructor and operator= functions
36 // This must be placed in the private: declarations for a class.
37 //
38 // For disallowing only assign or copy, delete the relevant operator or
39 // constructor, for example:
40 // void operator=(const TypeName&) = delete;
41 // Note, that most uses of DISALLOW_ASSIGN and DISALLOW_COPY are broken
42 // semantically, one should either use disallow both or neither. Try to
43 // avoid these in new code.
44 //
45 // When building with C++11 toolchains, just use the language support
46 // for explicitly deleted methods.
47 #if __cplusplus >= 201103L
48 #define DISALLOW_COPY_AND_ASSIGN(TypeName) \
49 TypeName(const TypeName&) = delete; \
50 void operator=(const TypeName&) = delete
51 #else
52 #define DISALLOW_COPY_AND_ASSIGN(TypeName) \
53 TypeName(const TypeName&); \
54 void operator=(const TypeName&)
55 #endif
56
57 // A macro to disallow all the implicit constructors, namely the
58 // default constructor, copy constructor and operator= functions.
59 //
60 // This should be used in the private: declarations for a class
61 // that wants to prevent anyone from instantiating it. This is
62 // especially useful for classes containing only static methods.
63 #define DISALLOW_IMPLICIT_CONSTRUCTORS(TypeName) \
64 TypeName(); \
65 DISALLOW_COPY_AND_ASSIGN(TypeName)
66
67 // The arraysize(arr) macro returns the # of elements in an array arr.
68 // The expression is a compile-time constant, and therefore can be
69 // used in defining new arrays, for example. If you use arraysize on
70 // a pointer by mistake, you will get a compile-time error.
71 //
72 // One caveat is that arraysize() doesn't accept any array of an
73 // anonymous type or a type defined inside a function. In these rare
74 // cases, you have to use the unsafe ARRAYSIZE_UNSAFE() macro below. This is
75 // due to a limitation in C++'s template system. The limitation might
76 // eventually be removed, but it hasn't happened yet.
77
78 // This template function declaration is used in defining arraysize.
79 // Note that the function doesn't need an implementation, as we only
80 // use its type.
81 template <typename T, size_t N>
82 char(&ArraySizeHelper(T(&array)[N]))[N]; // NOLINT(readability/casting)
83
84 #define arraysize(array) (sizeof(ArraySizeHelper(array)))
85
86 // ARRAYSIZE_UNSAFE performs essentially the same calculation as arraysize,
87 // but can be used on anonymous types or types defined inside
88 // functions. It's less safe than arraysize as it accepts some
89 // (although not all) pointers. Therefore, you should use arraysize
90 // whenever possible.
91 //
92 // The expression ARRAYSIZE_UNSAFE(a) is a compile-time constant of type
93 // size_t.
94 //
95 // ARRAYSIZE_UNSAFE catches a few type errors. If you see a compiler error
96 //
97 // "warning: division by zero in ..."
98 //
99 // when using ARRAYSIZE_UNSAFE, you are (wrongfully) giving it a pointer.
100 // You should only use ARRAYSIZE_UNSAFE on statically allocated arrays.
101 //
102 // The following comments are on the implementation details, and can
103 // be ignored by the users.
104 //
105 // ARRAYSIZE_UNSAFE(arr) works by inspecting sizeof(arr) (the # of bytes in
106 // the array) and sizeof(*(arr)) (the # of bytes in one array
107 // element). If the former is divisible by the latter, perhaps arr is
108 // indeed an array, in which case the division result is the # of
109 // elements in the array. Otherwise, arr cannot possibly be an array,
110 // and we generate a compiler error to prevent the code from
111 // compiling.
112 //
113 // Since the size of bool is implementation-defined, we need to cast
114 // !(sizeof(a) & sizeof(*(a))) to size_t in order to ensure the final
115 // result has type size_t.
116 //
117 // This macro is not perfect as it wrongfully accepts certain
118 // pointers, namely where the pointer size is divisible by the pointee
119 // size. Since all our code has to go through a 32-bit compiler,
120 // where a pointer is 4 bytes, this means all pointers to a type whose
121 // size is 3 or greater than 4 will be (righteously) rejected.
122 #define ARRAYSIZE_UNSAFE(a) \
123 ((sizeof(a) / sizeof(*(a))) / \
124 static_cast<size_t>(!(sizeof(a) % sizeof(*(a)))))
125
126 #define LIKELY(x) __builtin_expect((x), true)
127 #define UNLIKELY(x) __builtin_expect((x), false)
128
129 #define WARN_UNUSED __attribute__((warn_unused_result))
130
131 // A deprecated function to call to create a false use of the parameter, for
132 // example:
133 // int foo(int x) { UNUSED(x); return 10; }
134 // to avoid compiler warnings. Going forward we prefer ATTRIBUTE_UNUSED.
135 template <typename... T>
UNUSED(const T &...)136 void UNUSED(const T&...) {
137 }
138
139 // An attribute to place on a parameter to a function, for example:
140 // int foo(int x ATTRIBUTE_UNUSED) { return 10; }
141 // to avoid compiler warnings.
142 #define ATTRIBUTE_UNUSED __attribute__((__unused__))
143
144 // The FALLTHROUGH_INTENDED macro can be used to annotate implicit fall-through
145 // between switch labels:
146 // switch (x) {
147 // case 40:
148 // case 41:
149 // if (truth_is_out_there) {
150 // ++x;
151 // FALLTHROUGH_INTENDED; // Use instead of/along with annotations in
152 // // comments.
153 // } else {
154 // return x;
155 // }
156 // case 42:
157 // ...
158 //
159 // As shown in the example above, the FALLTHROUGH_INTENDED macro should be
160 // followed by a semicolon. It is designed to mimic control-flow statements
161 // like 'break;', so it can be placed in most places where 'break;' can, but
162 // only if there are no statements on the execution path between it and the
163 // next switch label.
164 //
165 // When compiled with clang in C++11 mode, the FALLTHROUGH_INTENDED macro is
166 // expanded to [[clang::fallthrough]] attribute, which is analysed when
167 // performing switch labels fall-through diagnostic ('-Wimplicit-fallthrough').
168 // See clang documentation on language extensions for details:
169 // http://clang.llvm.org/docs/LanguageExtensions.html#clang__fallthrough
170 //
171 // When used with unsupported compilers, the FALLTHROUGH_INTENDED macro has no
172 // effect on diagnostics.
173 //
174 // In either case this macro has no effect on runtime behavior and performance
175 // of code.
176 #if defined(__clang__) && __cplusplus >= 201103L && defined(__has_warning)
177 #if __has_feature(cxx_attributes) && __has_warning("-Wimplicit-fallthrough")
178 #define FALLTHROUGH_INTENDED [[clang::fallthrough]] // NOLINT
179 #endif
180 #endif
181
182 #ifndef FALLTHROUGH_INTENDED
183 #define FALLTHROUGH_INTENDED \
184 do { \
185 } while (0)
186 #endif
187
188 #endif // ANDROID_BASE_MACROS_H
189