| blob | 0786cb2fe5c5f1594ad1534e05dff77514e4ebf8 |
1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
3 /* This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 /* Implementations of various class and method modifier attributes. */
9 #ifndef mozilla_Attributes_h
10 #define mozilla_Attributes_h
14 /*
15 * MOZ_ALWAYS_INLINE is a macro which expands to tell the compiler that the
16 * method decorated with it must be inlined, even if the compiler thinks
17 * otherwise. This is only a (much) stronger version of the inline hint:
18 * compilers are not guaranteed to respect it (although they're much more likely
19 * to do so).
20 *
21 * The MOZ_ALWAYS_INLINE_EVEN_DEBUG macro is yet stronger. It tells the
22 * compiler to inline even in DEBUG builds. It should be used very rarely.
23 */
24 #if defined(_MSC_VER)
25 # define MOZ_ALWAYS_INLINE_EVEN_DEBUG __forceinline
26 #elif defined(__GNUC__)
27 # define MOZ_ALWAYS_INLINE_EVEN_DEBUG __attribute__((always_inline)) inline
28 #else
29 # define MOZ_ALWAYS_INLINE_EVEN_DEBUG inline
30 #endif
32 #if !defined(DEBUG)
33 # define MOZ_ALWAYS_INLINE MOZ_ALWAYS_INLINE_EVEN_DEBUG
34 #elif defined(_MSC_VER) && !defined(__cplusplus)
35 # define MOZ_ALWAYS_INLINE __inline
36 #else
37 # define MOZ_ALWAYS_INLINE inline
38 #endif
40 /*
41 * g++ requires -std=c++0x or -std=gnu++0x to support C++11 functionality
42 * without warnings (functionality used by the macros below). These modes are
43 * detectable by checking whether __GXX_EXPERIMENTAL_CXX0X__ is defined or, more
44 * standardly, by checking whether __cplusplus has a C++11 or greater value.
45 * Current versions of g++ do not correctly set __cplusplus, so we check both
46 * for forward compatibility.
47 */
48 #if defined(__clang__)
49 /*
50 * Per Clang documentation, "Note that marketing version numbers should not
51 * be used to check for language features, as different vendors use different
52 * numbering schemes. Instead, use the feature checking macros."
53 */
54 # ifndef __has_extension
56 # endif
57 # if __has_extension(cxx_constexpr)
58 # define MOZ_HAVE_CXX11_CONSTEXPR
59 # endif
60 # if __has_extension(cxx_deleted_functions)
61 # define MOZ_HAVE_CXX11_DELETE
62 # endif
63 # if __has_extension(cxx_override_control)
64 # define MOZ_HAVE_CXX11_OVERRIDE
65 # define MOZ_HAVE_CXX11_FINAL final
66 # endif
67 # if __has_attribute(noinline)
68 # define MOZ_HAVE_NEVER_INLINE __attribute__((noinline))
69 # endif
70 # if __has_attribute(noreturn)
71 # define MOZ_HAVE_NORETURN __attribute__((noreturn))
72 # endif
73 #elif defined(__GNUC__)
74 # if defined(__GXX_EXPERIMENTAL_CXX0X__) || __cplusplus >= 201103L
75 # if MOZ_GCC_VERSION_AT_LEAST(4, 7, 0)
76 # define MOZ_HAVE_CXX11_OVERRIDE
77 # define MOZ_HAVE_CXX11_FINAL final
78 # endif
79 # if MOZ_GCC_VERSION_AT_LEAST(4, 6, 0)
80 # define MOZ_HAVE_CXX11_CONSTEXPR
81 # endif
82 # define MOZ_HAVE_CXX11_DELETE
83 # else
84 /* __final is a non-C++11 GCC synonym for 'final', per GCC r176655. */
85 # if MOZ_GCC_VERSION_AT_LEAST(4, 7, 0)
86 # define MOZ_HAVE_CXX11_FINAL __final
87 # endif
88 # endif
89 # define MOZ_HAVE_NEVER_INLINE __attribute__((noinline))
90 # define MOZ_HAVE_NORETURN __attribute__((noreturn))
91 #elif defined(_MSC_VER)
92 # if _MSC_VER >= 1700
93 # define MOZ_HAVE_CXX11_FINAL final
94 # else
95 /* MSVC <= 10 used to spell "final" as "sealed". */
96 # define MOZ_HAVE_CXX11_FINAL sealed
97 # endif
98 # define MOZ_HAVE_CXX11_OVERRIDE
99 # define MOZ_HAVE_NEVER_INLINE __declspec(noinline)
100 # define MOZ_HAVE_NORETURN __declspec(noreturn)
101 #endif
103 /*
104 * The MOZ_CONSTEXPR specifier declares that a C++11 compiler can evaluate a
105 * function at compile time. A constexpr function cannot examine any values
106 * except its arguments and can have no side effects except its return value.
107 * The MOZ_CONSTEXPR_VAR specifier tells a C++11 compiler that a variable's
108 * value may be computed at compile time. It should be prefered to just
109 * marking variables as MOZ_CONSTEXPR because if the compiler does not support
110 * constexpr it will fall back to making the variable const, and some compilers
111 * do not accept variables being marked both const and constexpr.
112 */
113 #ifdef MOZ_HAVE_CXX11_CONSTEXPR
114 # define MOZ_CONSTEXPR constexpr
115 # define MOZ_CONSTEXPR_VAR constexpr
116 #else
118 # define MOZ_CONSTEXPR_VAR const
119 #endif
121 /*
122 * MOZ_NEVER_INLINE is a macro which expands to tell the compiler that the
123 * method decorated with it must never be inlined, even if the compiler would
124 * otherwise choose to inline the method. Compilers aren't absolutely
125 * guaranteed to support this, but most do.
126 */
127 #if defined(MOZ_HAVE_NEVER_INLINE)
128 # define MOZ_NEVER_INLINE MOZ_HAVE_NEVER_INLINE
129 #else
131 #endif
133 /*
134 * MOZ_NORETURN, specified at the start of a function declaration, indicates
135 * that the given function does not return. (The function definition does not
136 * need to be annotated.)
137 *
138 * MOZ_NORETURN void abort(const char* msg);
139 *
140 * This modifier permits the compiler to optimize code assuming a call to such a
141 * function will never return. It also enables the compiler to avoid spurious
142 * warnings about not initializing variables, or about any other seemingly-dodgy
143 * operations performed after the function returns.
144 *
145 * This modifier does not affect the corresponding function's linking behavior.
146 */
147 #if defined(MOZ_HAVE_NORETURN)
148 # define MOZ_NORETURN MOZ_HAVE_NORETURN
149 #else
151 #endif
153 /*
154 * MOZ_ASAN_BLACKLIST is a macro to tell AddressSanitizer (a compile-time
155 * instrumentation shipped with Clang) to not instrument the annotated function.
156 * Furthermore, it will prevent the compiler from inlining the function because
157 * inlining currently breaks the blacklisting mechanism of AddressSanitizer.
158 */
159 #if defined(__has_feature)
160 # if __has_feature(address_sanitizer)
161 # define MOZ_ASAN_BLACKLIST MOZ_NEVER_INLINE __attribute__((no_sanitize_address))
162 # else
164 # endif
165 #else
167 #endif
169 /*
170 * MOZ_TSAN_BLACKLIST is a macro to tell ThreadSanitizer (a compile-time
171 * instrumentation shipped with Clang) to not instrument the annotated function.
172 * Furthermore, it will prevent the compiler from inlining the function because
173 * inlining currently breaks the blacklisting mechanism of ThreadSanitizer.
174 */
175 #if defined(__has_feature)
176 # if __has_feature(thread_sanitizer)
177 # define MOZ_TSAN_BLACKLIST MOZ_NEVER_INLINE __attribute__((no_sanitize_thread))
178 # else
180 # endif
181 #else
183 #endif
185 #ifdef __cplusplus
187 /*
188 * MOZ_DELETE, specified immediately prior to the ';' terminating an undefined-
189 * method declaration, attempts to delete that method from the corresponding
190 * class. An attempt to use the method will always produce an error *at compile
191 * time* (instead of sometimes as late as link time) when this macro can be
192 * implemented. For example, you can use MOZ_DELETE to produce classes with no
193 * implicit copy constructor or assignment operator:
194 *
195 * struct NonCopyable
196 * {
197 * private:
198 * NonCopyable(const NonCopyable& other) MOZ_DELETE;
199 * void operator=(const NonCopyable& other) MOZ_DELETE;
200 * };
201 *
202 * If MOZ_DELETE can't be implemented for the current compiler, use of the
203 * annotated method will still cause an error, but the error might occur at link
204 * time in some cases rather than at compile time.
205 *
206 * MOZ_DELETE relies on C++11 functionality not universally implemented. As a
207 * backstop, method declarations using MOZ_DELETE should be private.
208 */
209 #if defined(MOZ_HAVE_CXX11_DELETE)
210 # define MOZ_DELETE = delete
211 #else
213 #endif
215 /*
216 * MOZ_OVERRIDE explicitly indicates that a virtual member function in a class
217 * overrides a member function of a base class, rather than potentially being a
218 * new member function. MOZ_OVERRIDE should be placed immediately before the
219 * ';' terminating the member function's declaration, or before '= 0;' if the
220 * member function is pure. If the member function is defined in the class
221 * definition, it should appear before the opening brace of the function body.
222 *
223 * class Base
224 * {
225 * public:
226 * virtual void f() = 0;
227 * };
228 * class Derived1 : public Base
229 * {
230 * public:
231 * virtual void f() MOZ_OVERRIDE;
232 * };
233 * class Derived2 : public Base
234 * {
235 * public:
236 * virtual void f() MOZ_OVERRIDE = 0;
237 * };
238 * class Derived3 : public Base
239 * {
240 * public:
241 * virtual void f() MOZ_OVERRIDE { }
242 * };
243 *
244 * In compilers supporting C++11 override controls, MOZ_OVERRIDE *requires* that
245 * the function marked with it override a member function of a base class: it
246 * is a compile error if it does not. Otherwise MOZ_OVERRIDE does not affect
247 * semantics and merely documents the override relationship to the reader (but
248 * of course must still be used correctly to not break C++11 compilers).
249 */
250 #if defined(MOZ_HAVE_CXX11_OVERRIDE)
251 # define MOZ_OVERRIDE override
252 #else
254 #endif
256 /*
257 * MOZ_FINAL indicates that some functionality cannot be overridden through
258 * inheritance. It can be used to annotate either classes/structs or virtual
259 * member functions.
260 *
261 * To annotate a class/struct with MOZ_FINAL, place MOZ_FINAL immediately after
262 * the name of the class, before the list of classes from which it derives (if
263 * any) and before its opening brace. MOZ_FINAL must not be used to annotate
264 * unnamed classes or structs. (With some compilers, and with C++11 proper, the
265 * underlying expansion is ambiguous with specifying a class name.)
266 *
267 * class Base MOZ_FINAL
268 * {
269 * public:
270 * Base();
271 * ~Base();
272 * virtual void f() { }
273 * };
274 * // This will be an error in some compilers:
275 * class Derived : public Base
276 * {
277 * public:
278 * ~Derived() { }
279 * };
280 *
281 * One particularly common reason to specify MOZ_FINAL upon a class is to tell
282 * the compiler that it's not dangerous for it to have a non-virtual destructor
283 * yet have one or more virtual functions, silencing the warning it might emit
284 * in this case. Suppose Base above weren't annotated with MOZ_FINAL. Because
285 * ~Base() is non-virtual, an attempt to delete a Derived* through a Base*
286 * wouldn't call ~Derived(), so any cleanup ~Derived() might do wouldn't happen.
287 * (Formally C++ says behavior is undefined, but compilers will likely just call
288 * ~Base() and not ~Derived().) Specifying MOZ_FINAL tells the compiler that
289 * it's safe for the destructor to be non-virtual.
290 *
291 * In compilers implementing final controls, it is an error to inherit from a
292 * class annotated with MOZ_FINAL. In other compilers it serves only as
293 * documentation.
294 *
295 * To annotate a virtual member function with MOZ_FINAL, place MOZ_FINAL
296 * immediately before the ';' terminating the member function's declaration, or
297 * before '= 0;' if the member function is pure. If the member function is
298 * defined in the class definition, it should appear before the opening brace of
299 * the function body. (This placement is identical to that for MOZ_OVERRIDE.
300 * If both are used, they should appear in the order 'MOZ_FINAL MOZ_OVERRIDE'
301 * for consistency.)
302 *
303 * class Base
304 * {
305 * public:
306 * virtual void f() MOZ_FINAL;
307 * };
308 * class Derived
309 * {
310 * public:
311 * // This will be an error in some compilers:
312 * virtual void f();
313 * };
314 *
315 * In compilers implementing final controls, it is an error for a derived class
316 * to override a method annotated with MOZ_FINAL. In other compilers it serves
317 * only as documentation.
318 */
319 #if defined(MOZ_HAVE_CXX11_FINAL)
320 # define MOZ_FINAL MOZ_HAVE_CXX11_FINAL
321 #else
323 #endif
325 /**
326 * MOZ_WARN_UNUSED_RESULT tells the compiler to emit a warning if a function's
327 * return value is not used by the caller.
328 *
329 * Place this attribute at the very beginning of a function definition. For
330 * example, write
331 *
332 * MOZ_WARN_UNUSED_RESULT int foo();
333 *
334 * or
335 *
336 * MOZ_WARN_UNUSED_RESULT int foo() { return 42; }
337 */
338 #if defined(__GNUC__) || defined(__clang__)
339 # define MOZ_WARN_UNUSED_RESULT __attribute__ ((warn_unused_result))
340 #else
341 # define MOZ_WARN_UNUSED_RESULT
342 #endif
344 /*
345 * The following macros are attributes that support the static analysis plugin
346 * included with Mozilla, and will be implemented (when such support is enabled)
347 * as C++11 attributes. Since such attributes are legal pretty much everywhere
348 * and have subtly different semantics depending on their placement, the
349 * following is a guide on where to place the attributes.
350 *
351 * Attributes that apply to a struct or class precede the name of the class:
352 * (Note that this is different from the placement of MOZ_FINAL for classes!)
353 *
354 * class MOZ_CLASS_ATTRIBUTE SomeClass {};
355 *
356 * Attributes that apply to functions follow the parentheses and const
357 * qualifiers but precede MOZ_FINAL, MOZ_OVERRIDE and the function body:
358 *
359 * void DeclaredFunction() MOZ_FUNCTION_ATTRIBUTE;
360 * void SomeFunction() MOZ_FUNCTION_ATTRIBUTE {}
361 * void PureFunction() const MOZ_FUNCTION_ATTRIBUTE = 0;
362 * void OverriddenFunction() MOZ_FUNCTION_ATTIRBUTE MOZ_OVERRIDE;
363 *
364 * Attributes that apply to variables or parameters follow the variable's name:
365 *
366 * int variable MOZ_VARIABLE_ATTRIBUTE;
367 *
368 * Attributes that apply to types follow the type name:
369 *
370 * typedef int MOZ_TYPE_ATTRIBUTE MagicInt;
371 * int MOZ_TYPE_ATTRIBUTE someVariable;
372 * int * MOZ_TYPE_ATTRIBUTE magicPtrInt;
373 * int MOZ_TYPE_ATTRIBUTE * ptrToMagicInt;
374 *
375 * Attributes that apply to statements precede the statement:
376 *
377 * MOZ_IF_ATTRIBUTE if (x == 0)
378 * MOZ_DO_ATTRIBUTE do { } while(0);
379 *
380 * Attributes that apply to labels precede the label:
381 *
382 * MOZ_LABEL_ATTRIBUTE target:
383 * goto target;
384 * MOZ_CASE_ATTRIBUTE case 5:
385 * MOZ_DEFAULT_ATTRIBUTE default:
386 *
387 * The static analyses that are performed by the plugin are as follows:
388 *
389 * MOZ_MUST_OVERRIDE: Applies to all C++ member functions. All immediate
390 * subclasses must provide an exact override of this method; if a subclass
391 * does not override this method, the compiler will emit an error. This
392 * attribute is not limited to virtual methods, so if it is applied to a
393 * nonvirtual method and the subclass does not provide an equivalent
394 * definition, the compiler will emit an error.
395 * MOZ_STACK_CLASS: Applies to all classes. Any class with this annotation is
396 * expected to live on the stack, so it is a compile-time error to use it, or
397 * an array of such objects, as a global or static variable, or as the type of
398 * a new expression (unless placement new is being used). If a member of
399 * another class uses this class, or if another class inherits from this
400 * class, then it is considered to be a stack class as well, although this
401 * attribute need not be provided in such cases.
402 * MOZ_NONHEAP_CLASS: Applies to all classes. Any class with this annotation is
403 * expected to live on the stack or in static storage, so it is a compile-time
404 * error to use it, or an array of such objects, as the type of a new
405 * expression (unless placement new is being used). If a member of another
406 * class uses this class, or if another class inherits from this class, then
407 * it is considered to be a non-heap class as well, although this attribute
408 * need not be provided in such cases.
409 */
410 #ifdef MOZ_CLANG_PLUGIN
414 #else
420 /*
421 * MOZ_THIS_IN_INITIALIZER_LIST is used to avoid a warning when we know that
422 * it's safe to use 'this' in an initializer list.
423 */
424 #ifdef _MSC_VER
425 # define MOZ_THIS_IN_INITIALIZER_LIST() \
426 __pragma(warning(push)) \
427 __pragma(warning(disable:4355)) \
428 this \
429 __pragma(warning(pop))
430 #else
431 # define MOZ_THIS_IN_INITIALIZER_LIST() this
432 #endif