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