| blob | cdce8c7717319ef9c64c91395a18f86a036feb43 |
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 #if defined(_MSC_VER)
41 /*
42 * g++ requires -std=c++0x or -std=gnu++0x to support C++11 functionality
43 * without warnings (functionality used by the macros below). These modes are
44 * detectable by checking whether __GXX_EXPERIMENTAL_CXX0X__ is defined or, more
45 * standardly, by checking whether __cplusplus has a C++11 or greater value.
46 * Current versions of g++ do not correctly set __cplusplus, so we check both
47 * for forward compatibility.
48 *
49 * Even though some versions of MSVC support explicit conversion operators, we
50 * don't indicate support for them here, due to
51 * http://stackoverflow.com/questions/20498142/visual-studio-2013-explicit-keyword-bug
52 */
53 # if _MSC_VER >= 1800
54 # define MOZ_HAVE_CXX11_DELETE
55 # endif
56 # if _MSC_VER >= 1700
57 # define MOZ_HAVE_CXX11_FINAL final
58 # else
59 # if defined(__clang__)
60 # error Please do not try to use clang-cl with MSVC10 or below emulation!
61 # endif
62 /* MSVC <= 10 used to spell "final" as "sealed". */
63 # define MOZ_HAVE_CXX11_FINAL sealed
64 # endif
65 # define MOZ_HAVE_CXX11_OVERRIDE
66 # define MOZ_HAVE_NEVER_INLINE __declspec(noinline)
67 # define MOZ_HAVE_NORETURN __declspec(noreturn)
68 #elif defined(__clang__)
69 /*
70 * Per Clang documentation, "Note that marketing version numbers should not
71 * be used to check for language features, as different vendors use different
72 * numbering schemes. Instead, use the feature checking macros."
73 */
74 # ifndef __has_extension
76 # endif
77 # if __has_extension(cxx_constexpr)
78 # define MOZ_HAVE_CXX11_CONSTEXPR
79 # endif
80 # if __has_extension(cxx_explicit_conversions)
81 # define MOZ_HAVE_EXPLICIT_CONVERSION
82 # endif
83 # if __has_extension(cxx_deleted_functions)
84 # define MOZ_HAVE_CXX11_DELETE
85 # endif
86 # if __has_extension(cxx_override_control)
87 # define MOZ_HAVE_CXX11_OVERRIDE
88 # define MOZ_HAVE_CXX11_FINAL final
89 # endif
90 # if __has_attribute(noinline)
91 # define MOZ_HAVE_NEVER_INLINE __attribute__((noinline))
92 # endif
93 # if __has_attribute(noreturn)
94 # define MOZ_HAVE_NORETURN __attribute__((noreturn))
95 # endif
96 #elif defined(__GNUC__)
97 # if defined(__GXX_EXPERIMENTAL_CXX0X__) || __cplusplus >= 201103L
98 # if MOZ_GCC_VERSION_AT_LEAST(4, 7, 0)
99 # define MOZ_HAVE_CXX11_OVERRIDE
100 # define MOZ_HAVE_CXX11_FINAL final
101 # endif
102 # if MOZ_GCC_VERSION_AT_LEAST(4, 6, 0)
103 # define MOZ_HAVE_CXX11_CONSTEXPR
104 # endif
105 # if MOZ_GCC_VERSION_AT_LEAST(4, 5, 0)
106 # define MOZ_HAVE_EXPLICIT_CONVERSION
107 # endif
108 # define MOZ_HAVE_CXX11_DELETE
109 # else
110 /* __final is a non-C++11 GCC synonym for 'final', per GCC r176655. */
111 # if MOZ_GCC_VERSION_AT_LEAST(4, 7, 0)
112 # define MOZ_HAVE_CXX11_FINAL __final
113 # endif
114 # endif
115 # define MOZ_HAVE_NEVER_INLINE __attribute__((noinline))
116 # define MOZ_HAVE_NORETURN __attribute__((noreturn))
117 #endif
119 /*
120 * When built with clang analyzer (a.k.a scan-build), define MOZ_HAVE_NORETURN
121 * to mark some false positives
122 */
123 #ifdef __clang_analyzer__
124 # if __has_extension(attribute_analyzer_noreturn)
125 # define MOZ_HAVE_ANALYZER_NORETURN __attribute__((analyzer_noreturn))
126 # endif
127 #endif
129 /*
130 * The MOZ_CONSTEXPR specifier declares that a C++11 compiler can evaluate a
131 * function at compile time. A constexpr function cannot examine any values
132 * except its arguments and can have no side effects except its return value.
133 * The MOZ_CONSTEXPR_VAR specifier tells a C++11 compiler that a variable's
134 * value may be computed at compile time. It should be prefered to just
135 * marking variables as MOZ_CONSTEXPR because if the compiler does not support
136 * constexpr it will fall back to making the variable const, and some compilers
137 * do not accept variables being marked both const and constexpr.
138 */
139 #ifdef MOZ_HAVE_CXX11_CONSTEXPR
140 # define MOZ_CONSTEXPR constexpr
141 # define MOZ_CONSTEXPR_VAR constexpr
142 #else
144 # define MOZ_CONSTEXPR_VAR const
145 #endif
147 /*
148 * MOZ_EXPLICIT_CONVERSION is a specifier on a type conversion
149 * overloaded operator that declares that a C++11 compiler should restrict
150 * this operator to allow only explicit type conversions, disallowing
151 * implicit conversions.
152 *
153 * Example:
154 *
155 * template<typename T>
156 * class Ptr
157 * {
158 * T* mPtr;
159 * MOZ_EXPLICIT_CONVERSION operator bool() const
160 * {
161 * return mPtr != nullptr;
162 * }
163 * };
164 *
165 */
166 #ifdef MOZ_HAVE_EXPLICIT_CONVERSION
167 # define MOZ_EXPLICIT_CONVERSION explicit
168 #else
170 #endif
172 /*
173 * MOZ_NEVER_INLINE is a macro which expands to tell the compiler that the
174 * method decorated with it must never be inlined, even if the compiler would
175 * otherwise choose to inline the method. Compilers aren't absolutely
176 * guaranteed to support this, but most do.
177 */
178 #if defined(MOZ_HAVE_NEVER_INLINE)
179 # define MOZ_NEVER_INLINE MOZ_HAVE_NEVER_INLINE
180 #else
182 #endif
184 /*
185 * MOZ_NORETURN, specified at the start of a function declaration, indicates
186 * that the given function does not return. (The function definition does not
187 * need to be annotated.)
188 *
189 * MOZ_NORETURN void abort(const char* msg);
190 *
191 * This modifier permits the compiler to optimize code assuming a call to such a
192 * function will never return. It also enables the compiler to avoid spurious
193 * warnings about not initializing variables, or about any other seemingly-dodgy
194 * operations performed after the function returns.
195 *
196 * This modifier does not affect the corresponding function's linking behavior.
197 */
198 #if defined(MOZ_HAVE_NORETURN)
199 # define MOZ_NORETURN MOZ_HAVE_NORETURN
200 #else
202 #endif
204 /*
205 * MOZ_PRETEND_NORETURN_FOR_STATIC_ANALYSIS, specified at the end of a function
206 * declaration, indicates that for the purposes of static analysis, this
207 * function does not return. (The function definition does not need to be
208 * annotated.)
209 *
210 * MOZ_ReportCrash(const char* s, const char* file, int ln)
211 * MOZ_PRETEND_NORETURN_FOR_STATIC_ANALYSIS
212 *
213 * Some static analyzers, like scan-build from clang, can use this information
214 * to eliminate false positives. From the upstream documentation of scan-build:
215 * "This attribute is useful for annotating assertion handlers that actually
216 * can return, but for the purpose of using the analyzer we want to pretend
217 * that such functions do not return."
218 *
219 */
220 #if defined(MOZ_HAVE_ANALYZER_NORETURN)
221 # define MOZ_PRETEND_NORETURN_FOR_STATIC_ANALYSIS MOZ_HAVE_ANALYZER_NORETURN
222 #else
224 #endif
226 /*
227 * MOZ_ASAN_BLACKLIST is a macro to tell AddressSanitizer (a compile-time
228 * instrumentation shipped with Clang and GCC) to not instrument the annotated
229 * function. Furthermore, it will prevent the compiler from inlining the
230 * function because inlining currently breaks the blacklisting mechanism of
231 * AddressSanitizer.
232 */
233 #if defined(__has_feature)
234 # if __has_feature(address_sanitizer)
235 # define MOZ_HAVE_ASAN_BLACKLIST
236 # endif
237 #elif defined(__GNUC__)
238 # if defined(__SANITIZE_ADDRESS__)
239 # define MOZ_HAVE_ASAN_BLACKLIST
240 # endif
241 #endif
243 #if defined(MOZ_HAVE_ASAN_BLACKLIST)
244 # define MOZ_ASAN_BLACKLIST MOZ_NEVER_INLINE __attribute__((no_sanitize_address))
245 #else
247 #endif
249 /*
250 * MOZ_TSAN_BLACKLIST is a macro to tell ThreadSanitizer (a compile-time
251 * instrumentation shipped with Clang) to not instrument the annotated function.
252 * Furthermore, it will prevent the compiler from inlining the function because
253 * inlining currently breaks the blacklisting mechanism of ThreadSanitizer.
254 */
255 #if defined(__has_feature)
256 # if __has_feature(thread_sanitizer)
257 # define MOZ_TSAN_BLACKLIST MOZ_NEVER_INLINE __attribute__((no_sanitize_thread))
258 # else
260 # endif
261 #else
263 #endif
265 #ifdef __cplusplus
267 /*
268 * MOZ_DELETE, specified immediately prior to the ';' terminating an undefined-
269 * method declaration, attempts to delete that method from the corresponding
270 * class. An attempt to use the method will always produce an error *at compile
271 * time* (instead of sometimes as late as link time) when this macro can be
272 * implemented. For example, you can use MOZ_DELETE to produce classes with no
273 * implicit copy constructor or assignment operator:
274 *
275 * struct NonCopyable
276 * {
277 * private:
278 * NonCopyable(const NonCopyable& aOther) MOZ_DELETE;
279 * void operator=(const NonCopyable& aOther) MOZ_DELETE;
280 * };
281 *
282 * If MOZ_DELETE can't be implemented for the current compiler, use of the
283 * annotated method will still cause an error, but the error might occur at link
284 * time in some cases rather than at compile time.
285 *
286 * MOZ_DELETE relies on C++11 functionality not universally implemented. As a
287 * backstop, method declarations using MOZ_DELETE should be private.
288 */
289 #if defined(MOZ_HAVE_CXX11_DELETE)
290 # define MOZ_DELETE = delete
291 #else
293 #endif
295 /*
296 * MOZ_OVERRIDE explicitly indicates that a virtual member function in a class
297 * overrides a member function of a base class, rather than potentially being a
298 * new member function. MOZ_OVERRIDE should be placed immediately before the
299 * ';' terminating the member function's declaration, or before '= 0;' if the
300 * member function is pure. If the member function is defined in the class
301 * definition, it should appear before the opening brace of the function body.
302 *
303 * class Base
304 * {
305 * public:
306 * virtual void f() = 0;
307 * };
308 * class Derived1 : public Base
309 * {
310 * public:
311 * virtual void f() MOZ_OVERRIDE;
312 * };
313 * class Derived2 : public Base
314 * {
315 * public:
316 * virtual void f() MOZ_OVERRIDE = 0;
317 * };
318 * class Derived3 : public Base
319 * {
320 * public:
321 * virtual void f() MOZ_OVERRIDE { }
322 * };
323 *
324 * In compilers supporting C++11 override controls, MOZ_OVERRIDE *requires* that
325 * the function marked with it override a member function of a base class: it
326 * is a compile error if it does not. Otherwise MOZ_OVERRIDE does not affect
327 * semantics and merely documents the override relationship to the reader (but
328 * of course must still be used correctly to not break C++11 compilers).
329 */
330 #if defined(MOZ_HAVE_CXX11_OVERRIDE)
331 # define MOZ_OVERRIDE override
332 #else
334 #endif
336 /*
337 * MOZ_FINAL indicates that some functionality cannot be overridden through
338 * inheritance. It can be used to annotate either classes/structs or virtual
339 * member functions.
340 *
341 * To annotate a class/struct with MOZ_FINAL, place MOZ_FINAL immediately after
342 * the name of the class, before the list of classes from which it derives (if
343 * any) and before its opening brace. MOZ_FINAL must not be used to annotate
344 * unnamed classes or structs. (With some compilers, and with C++11 proper, the
345 * underlying expansion is ambiguous with specifying a class name.)
346 *
347 * class Base MOZ_FINAL
348 * {
349 * public:
350 * Base();
351 * ~Base();
352 * virtual void f() { }
353 * };
354 * // This will be an error in some compilers:
355 * class Derived : public Base
356 * {
357 * public:
358 * ~Derived() { }
359 * };
360 *
361 * One particularly common reason to specify MOZ_FINAL upon a class is to tell
362 * the compiler that it's not dangerous for it to have a non-virtual destructor
363 * yet have one or more virtual functions, silencing the warning it might emit
364 * in this case. Suppose Base above weren't annotated with MOZ_FINAL. Because
365 * ~Base() is non-virtual, an attempt to delete a Derived* through a Base*
366 * wouldn't call ~Derived(), so any cleanup ~Derived() might do wouldn't happen.
367 * (Formally C++ says behavior is undefined, but compilers will likely just call
368 * ~Base() and not ~Derived().) Specifying MOZ_FINAL tells the compiler that
369 * it's safe for the destructor to be non-virtual.
370 *
371 * In compilers implementing final controls, it is an error to inherit from a
372 * class annotated with MOZ_FINAL. In other compilers it serves only as
373 * documentation.
374 *
375 * To annotate a virtual member function with MOZ_FINAL, place MOZ_FINAL
376 * immediately before the ';' terminating the member function's declaration, or
377 * before '= 0;' if the member function is pure. If the member function is
378 * defined in the class definition, it should appear before the opening brace of
379 * the function body. (This placement is identical to that for MOZ_OVERRIDE.
380 * If both are used, they should appear in the order 'MOZ_FINAL MOZ_OVERRIDE'
381 * for consistency.)
382 *
383 * class Base
384 * {
385 * public:
386 * virtual void f() MOZ_FINAL;
387 * };
388 * class Derived
389 * {
390 * public:
391 * // This will be an error in some compilers:
392 * virtual void f();
393 * };
394 *
395 * In compilers implementing final controls, it is an error for a derived class
396 * to override a method annotated with MOZ_FINAL. In other compilers it serves
397 * only as documentation.
398 */
399 #if defined(MOZ_HAVE_CXX11_FINAL)
400 # define MOZ_FINAL MOZ_HAVE_CXX11_FINAL
401 #else
403 #endif
405 /**
406 * MOZ_WARN_UNUSED_RESULT tells the compiler to emit a warning if a function's
407 * return value is not used by the caller.
408 *
409 * Place this attribute at the very beginning of a function definition. For
410 * example, write
411 *
412 * MOZ_WARN_UNUSED_RESULT int foo();
413 *
414 * or
415 *
416 * MOZ_WARN_UNUSED_RESULT int foo() { return 42; }
417 */
418 #if defined(__GNUC__) || defined(__clang__)
419 # define MOZ_WARN_UNUSED_RESULT __attribute__ ((warn_unused_result))
420 #else
421 # define MOZ_WARN_UNUSED_RESULT
422 #endif
424 /*
425 * The following macros are attributes that support the static analysis plugin
426 * included with Mozilla, and will be implemented (when such support is enabled)
427 * as C++11 attributes. Since such attributes are legal pretty much everywhere
428 * and have subtly different semantics depending on their placement, the
429 * following is a guide on where to place the attributes.
430 *
431 * Attributes that apply to a struct or class precede the name of the class:
432 * (Note that this is different from the placement of MOZ_FINAL for classes!)
433 *
434 * class MOZ_CLASS_ATTRIBUTE SomeClass {};
435 *
436 * Attributes that apply to functions follow the parentheses and const
437 * qualifiers but precede MOZ_FINAL, MOZ_OVERRIDE and the function body:
438 *
439 * void DeclaredFunction() MOZ_FUNCTION_ATTRIBUTE;
440 * void SomeFunction() MOZ_FUNCTION_ATTRIBUTE {}
441 * void PureFunction() const MOZ_FUNCTION_ATTRIBUTE = 0;
442 * void OverriddenFunction() MOZ_FUNCTION_ATTIRBUTE MOZ_OVERRIDE;
443 *
444 * Attributes that apply to variables or parameters follow the variable's name:
445 *
446 * int variable MOZ_VARIABLE_ATTRIBUTE;
447 *
448 * Attributes that apply to types follow the type name:
449 *
450 * typedef int MOZ_TYPE_ATTRIBUTE MagicInt;
451 * int MOZ_TYPE_ATTRIBUTE someVariable;
452 * int* MOZ_TYPE_ATTRIBUTE magicPtrInt;
453 * int MOZ_TYPE_ATTRIBUTE* ptrToMagicInt;
454 *
455 * Attributes that apply to statements precede the statement:
456 *
457 * MOZ_IF_ATTRIBUTE if (x == 0)
458 * MOZ_DO_ATTRIBUTE do { } while (0);
459 *
460 * Attributes that apply to labels precede the label:
461 *
462 * MOZ_LABEL_ATTRIBUTE target:
463 * goto target;
464 * MOZ_CASE_ATTRIBUTE case 5:
465 * MOZ_DEFAULT_ATTRIBUTE default:
466 *
467 * The static analyses that are performed by the plugin are as follows:
468 *
469 * MOZ_MUST_OVERRIDE: Applies to all C++ member functions. All immediate
470 * subclasses must provide an exact override of this method; if a subclass
471 * does not override this method, the compiler will emit an error. This
472 * attribute is not limited to virtual methods, so if it is applied to a
473 * nonvirtual method and the subclass does not provide an equivalent
474 * definition, the compiler will emit an error.
475 * MOZ_STACK_CLASS: Applies to all classes. Any class with this annotation is
476 * expected to live on the stack, so it is a compile-time error to use it, or
477 * an array of such objects, as a global or static variable, or as the type of
478 * a new expression (unless placement new is being used). If a member of
479 * another class uses this class, or if another class inherits from this
480 * class, then it is considered to be a stack class as well, although this
481 * attribute need not be provided in such cases.
482 * MOZ_NONHEAP_CLASS: Applies to all classes. Any class with this annotation is
483 * expected to live on the stack or in static storage, so it is a compile-time
484 * error to use it, or an array of such objects, as the type of a new
485 * expression (unless placement new is being used). If a member of another
486 * class uses this class, or if another class inherits from this class, then
487 * it is considered to be a non-heap class as well, although this attribute
488 * need not be provided in such cases.
489 * MOZ_HEAP_ALLOCATOR: Applies to any function. This indicates that the return
490 * value is allocated on the heap, and will as a result check such allocations
491 * during MOZ_STACK_CLASS and MOZ_NONHEAP_CLASS annotation checking.
492 * MOZ_IMPLICIT: Applies to constructors. Implicit conversion constructors
493 * are disallowed by default unless they are marked as MOZ_IMPLICIT. This
494 * attribute must be used for constructors which intend to provide implicit
495 * conversions.
496 */
497 #ifdef MOZ_CLANG_PLUGIN
502 /*
503 * It turns out that clang doesn't like void func() __attribute__ {} without a
504 * warning, so use pragmas to disable the warning. This code won't work on GCC
505 * anyways, so the warning is safe to ignore.
506 */
507 # define MOZ_HEAP_ALLOCATOR \
512 #else
520 /*
521 * MOZ_THIS_IN_INITIALIZER_LIST is used to avoid a warning when we know that
522 * it's safe to use 'this' in an initializer list.
523 */
524 #ifdef _MSC_VER
525 # define MOZ_THIS_IN_INITIALIZER_LIST() \
526 __pragma(warning(push)) \
527 __pragma(warning(disable:4355)) \
528 this \
529 __pragma(warning(pop))
530 #else
531 # define MOZ_THIS_IN_INITIALIZER_LIST() this
532 #endif