| blob | d48dc28f5c0e24b2dc06bb10772ff1eaeef42f2a |
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 # define MOZ_HAVE_NEVER_INLINE __declspec(noinline)
50 # define MOZ_HAVE_NORETURN __declspec(noreturn)
51 #elif defined(__clang__)
52 /*
53 * Per Clang documentation, "Note that marketing version numbers should not
54 * be used to check for language features, as different vendors use different
55 * numbering schemes. Instead, use the feature checking macros."
56 */
57 # ifndef __has_extension
58 # define __has_extension \
60 # endif
61 # if __has_attribute(noinline)
62 # define MOZ_HAVE_NEVER_INLINE __attribute__((noinline))
63 # endif
64 # if __has_attribute(noreturn)
65 # define MOZ_HAVE_NORETURN __attribute__((noreturn))
66 # endif
67 #elif defined(__GNUC__)
68 # define MOZ_HAVE_NEVER_INLINE __attribute__((noinline))
69 # define MOZ_HAVE_NORETURN __attribute__((noreturn))
70 # define MOZ_HAVE_NORETURN_PTR __attribute__((noreturn))
71 #endif
73 #if defined(__clang__)
74 # if __has_attribute(no_stack_protector)
75 # define MOZ_HAVE_NO_STACK_PROTECTOR __attribute__((no_stack_protector))
76 # endif
77 #elif defined(__GNUC__)
78 # define MOZ_HAVE_NO_STACK_PROTECTOR __attribute__((no_stack_protector))
79 #endif
81 /*
82 * When built with clang analyzer (a.k.a scan-build), define MOZ_HAVE_NORETURN
83 * to mark some false positives
84 */
85 #ifdef __clang_analyzer__
86 # if __has_extension(attribute_analyzer_noreturn)
87 # define MOZ_HAVE_ANALYZER_NORETURN __attribute__((analyzer_noreturn))
88 # endif
89 #endif
91 /*
92 * MOZ_NEVER_INLINE is a macro which expands to tell the compiler that the
93 * method decorated with it must never be inlined, even if the compiler would
94 * otherwise choose to inline the method. Compilers aren't absolutely
95 * guaranteed to support this, but most do.
96 */
97 #if defined(MOZ_HAVE_NEVER_INLINE)
98 # define MOZ_NEVER_INLINE MOZ_HAVE_NEVER_INLINE
99 #else
101 #endif
103 /*
104 * MOZ_NEVER_INLINE_DEBUG is a macro which expands to MOZ_NEVER_INLINE
105 * in debug builds, and nothing in opt builds.
106 */
107 #if defined(DEBUG)
108 # define MOZ_NEVER_INLINE_DEBUG MOZ_NEVER_INLINE
109 #else
111 #endif
112 /*
113 * MOZ_NORETURN, specified at the start of a function declaration, indicates
114 * that the given function does not return. (The function definition does not
115 * need to be annotated.)
116 *
117 * MOZ_NORETURN void abort(const char* msg);
118 *
119 * This modifier permits the compiler to optimize code assuming a call to such a
120 * function will never return. It also enables the compiler to avoid spurious
121 * warnings about not initializing variables, or about any other seemingly-dodgy
122 * operations performed after the function returns.
123 *
124 * There are two variants. The GCC version of NORETURN may be applied to a
125 * function pointer, while for MSVC it may not.
126 *
127 * This modifier does not affect the corresponding function's linking behavior.
128 */
129 #if defined(MOZ_HAVE_NORETURN)
130 # define MOZ_NORETURN MOZ_HAVE_NORETURN
131 #else
133 #endif
134 #if defined(MOZ_HAVE_NORETURN_PTR)
135 # define MOZ_NORETURN_PTR MOZ_HAVE_NORETURN_PTR
136 #else
138 #endif
140 /**
141 * MOZ_COLD tells the compiler that a function is "cold", meaning infrequently
142 * executed. This may lead it to optimize for size more aggressively than speed,
143 * or to allocate the body of the function in a distant part of the text segment
144 * to help keep it from taking up unnecessary icache when it isn't in use.
145 *
146 * Place this attribute at the very beginning of a function definition. For
147 * example, write
148 *
149 * MOZ_COLD int foo();
150 *
151 * or
152 *
153 * MOZ_COLD int foo() { return 42; }
154 */
155 #if defined(__GNUC__) || defined(__clang__)
156 # define MOZ_COLD __attribute__((cold))
157 #else
158 # define MOZ_COLD
159 #endif
161 /**
162 * MOZ_NONNULL tells the compiler that some of the arguments to a function are
163 * known to be non-null. The arguments are a list of 1-based argument indexes
164 * identifying arguments which are known to be non-null.
165 *
166 * Place this attribute at the very beginning of a function definition. For
167 * example, write
168 *
169 * MOZ_NONNULL(1, 2) int foo(char *p, char *q);
170 */
171 #if defined(__GNUC__) || defined(__clang__)
172 # define MOZ_NONNULL(...) __attribute__((nonnull(__VA_ARGS__)))
173 #else
174 # define MOZ_NONNULL(...)
175 #endif
177 /**
178 * MOZ_NONNULL_RETURN tells the compiler that the function's return value is
179 * guaranteed to be a non-null pointer, which may enable the compiler to
180 * optimize better at call sites.
181 *
182 * Place this attribute at the end of a function declaration. For example,
183 *
184 * char* foo(char *p, char *q) MOZ_NONNULL_RETURN;
185 */
186 #if defined(__GNUC__) || defined(__clang__)
187 # define MOZ_NONNULL_RETURN __attribute__((returns_nonnull))
188 #else
189 # define MOZ_NONNULL_RETURN
190 #endif
192 /*
193 * MOZ_PRETEND_NORETURN_FOR_STATIC_ANALYSIS, specified at the end of a function
194 * declaration, indicates that for the purposes of static analysis, this
195 * function does not return. (The function definition does not need to be
196 * annotated.)
197 *
198 * MOZ_ReportCrash(const char* s, const char* file, int ln)
199 * MOZ_PRETEND_NORETURN_FOR_STATIC_ANALYSIS
200 *
201 * Some static analyzers, like scan-build from clang, can use this information
202 * to eliminate false positives. From the upstream documentation of scan-build:
203 * "This attribute is useful for annotating assertion handlers that actually
204 * can return, but for the purpose of using the analyzer we want to pretend
205 * that such functions do not return."
206 *
207 */
208 #if defined(MOZ_HAVE_ANALYZER_NORETURN)
209 # define MOZ_PRETEND_NORETURN_FOR_STATIC_ANALYSIS MOZ_HAVE_ANALYZER_NORETURN
210 #else
212 #endif
214 /*
215 * MOZ_ASAN_BLACKLIST is a macro to tell AddressSanitizer (a compile-time
216 * instrumentation shipped with Clang and GCC) to not instrument the annotated
217 * function. Furthermore, it will prevent the compiler from inlining the
218 * function because inlining currently breaks the blacklisting mechanism of
219 * AddressSanitizer.
220 */
221 #if defined(__has_feature)
222 # if __has_feature(address_sanitizer)
223 # define MOZ_HAVE_ASAN_BLACKLIST
224 # endif
225 #elif defined(__GNUC__)
226 # if defined(__SANITIZE_ADDRESS__)
227 # define MOZ_HAVE_ASAN_BLACKLIST
228 # endif
229 #endif
231 #if defined(MOZ_HAVE_ASAN_BLACKLIST)
232 # define MOZ_ASAN_BLACKLIST \
233 MOZ_NEVER_INLINE __attribute__((no_sanitize_address))
234 #else
236 #endif
238 /*
239 * MOZ_TSAN_BLACKLIST is a macro to tell ThreadSanitizer (a compile-time
240 * instrumentation shipped with Clang) to not instrument the annotated function.
241 * Furthermore, it will prevent the compiler from inlining the function because
242 * inlining currently breaks the blacklisting mechanism of ThreadSanitizer.
243 */
244 #if defined(__has_feature)
245 # if __has_feature(thread_sanitizer)
246 # define MOZ_TSAN_BLACKLIST \
247 MOZ_NEVER_INLINE __attribute__((no_sanitize_thread))
248 # else
250 # endif
251 #else
253 #endif
255 #if defined(__has_attribute)
256 # if __has_attribute(no_sanitize)
257 # define MOZ_HAVE_NO_SANITIZE_ATTR
258 # endif
259 #endif
261 #ifdef __clang__
262 # ifdef MOZ_HAVE_NO_SANITIZE_ATTR
263 # define MOZ_HAVE_UNSIGNED_OVERFLOW_SANITIZE_ATTR
264 # define MOZ_HAVE_SIGNED_OVERFLOW_SANITIZE_ATTR
265 # endif
266 #endif
268 /*
269 * MOZ_NO_SANITIZE_UNSIGNED_OVERFLOW disables *un*signed integer overflow
270 * checking on the function it annotates, in builds configured to perform it.
271 * (Currently this is only Clang using -fsanitize=unsigned-integer-overflow, or
272 * via --enable-unsigned-overflow-sanitizer in Mozilla's build system.) It has
273 * no effect in other builds.
274 *
275 * Place this attribute at the very beginning of a function declaration.
276 *
277 * Unsigned integer overflow isn't *necessarily* a bug. It's well-defined in
278 * C/C++, and code may reasonably depend upon it. For example,
279 *
280 * MOZ_NO_SANITIZE_UNSIGNED_OVERFLOW inline bool
281 * IsDecimal(char aChar)
282 * {
283 * // For chars less than '0', unsigned integer underflow occurs, to a value
284 * // much greater than 10, so the overall test is false.
285 * // For chars greater than '0', no overflow occurs, and only '0' to '9'
286 * // pass the overall test.
287 * return static_cast<unsigned int>(aChar) - '0' < 10;
288 * }
289 *
290 * But even well-defined unsigned overflow often causes bugs when it occurs, so
291 * it should be restricted to functions annotated with this attribute.
292 *
293 * The compiler instrumentation to detect unsigned integer overflow has costs
294 * both at compile time and at runtime. Functions that are repeatedly inlined
295 * at compile time will also implicitly inline the necessary instrumentation,
296 * increasing compile time. Similarly, frequently-executed functions that
297 * require large amounts of instrumentation will also notice significant runtime
298 * slowdown to execute that instrumentation. Use this attribute to eliminate
299 * those costs -- but only after carefully verifying that no overflow can occur.
300 */
301 #ifdef MOZ_HAVE_UNSIGNED_OVERFLOW_SANITIZE_ATTR
302 # define MOZ_NO_SANITIZE_UNSIGNED_OVERFLOW \
304 #else
306 #endif
308 /*
309 * MOZ_NO_SANITIZE_SIGNED_OVERFLOW disables *signed* integer overflow checking
310 * on the function it annotates, in builds configured to perform it. (Currently
311 * this is only Clang using -fsanitize=signed-integer-overflow, or via
312 * --enable-signed-overflow-sanitizer in Mozilla's build system. GCC support
313 * will probably be added in the future.) It has no effect in other builds.
314 *
315 * Place this attribute at the very beginning of a function declaration.
316 *
317 * Signed integer overflow is undefined behavior in C/C++: *anything* can happen
318 * when it occurs. *Maybe* wraparound behavior will occur, but maybe also the
319 * compiler will assume no overflow happens and will adversely optimize the rest
320 * of your code. Code that contains signed integer overflow needs to be fixed.
321 *
322 * The compiler instrumentation to detect signed integer overflow has costs both
323 * at compile time and at runtime. Functions that are repeatedly inlined at
324 * compile time will also implicitly inline the necessary instrumentation,
325 * increasing compile time. Similarly, frequently-executed functions that
326 * require large amounts of instrumentation will also notice significant runtime
327 * slowdown to execute that instrumentation. Use this attribute to eliminate
328 * those costs -- but only after carefully verifying that no overflow can occur.
329 */
330 #ifdef MOZ_HAVE_SIGNED_OVERFLOW_SANITIZE_ATTR
331 # define MOZ_NO_SANITIZE_SIGNED_OVERFLOW \
333 #else
335 #endif
337 #undef MOZ_HAVE_NO_SANITIZE_ATTR
339 /**
340 * MOZ_ALLOCATOR tells the compiler that the function it marks returns either a
341 * "fresh", "pointer-free" block of memory, or nullptr. "Fresh" means that the
342 * block is not pointed to by any other reachable pointer in the program.
343 * "Pointer-free" means that the block contains no pointers to any valid object
344 * in the program. It may be initialized with other (non-pointer) values.
345 *
346 * Placing this attribute on appropriate functions helps GCC analyze pointer
347 * aliasing more accurately in their callers.
348 *
349 * GCC warns if a caller ignores the value returned by a function marked with
350 * MOZ_ALLOCATOR: it is hard to imagine cases where dropping the value returned
351 * by a function that meets the criteria above would be intentional.
352 *
353 * Place this attribute after the argument list and 'this' qualifiers of a
354 * function definition. For example, write
355 *
356 * void *my_allocator(size_t) MOZ_ALLOCATOR;
357 *
358 * or
359 *
360 * void *my_allocator(size_t bytes) MOZ_ALLOCATOR { ... }
361 */
362 #if defined(__GNUC__) || defined(__clang__)
363 # define MOZ_ALLOCATOR __attribute__((malloc, warn_unused_result))
364 # define MOZ_INFALLIBLE_ALLOCATOR \
365 __attribute__((malloc, warn_unused_result, returns_nonnull))
366 #else
367 # define MOZ_ALLOCATOR
368 # define MOZ_INFALLIBLE_ALLOCATOR
369 #endif
371 /**
372 * MOZ_MAYBE_UNUSED suppresses compiler warnings about functions that are
373 * never called (in this build configuration, at least).
374 *
375 * Place this attribute at the very beginning of a function declaration. For
376 * example, write
377 *
378 * MOZ_MAYBE_UNUSED int foo();
379 *
380 * or
381 *
382 * MOZ_MAYBE_UNUSED int foo() { return 42; }
383 */
384 #if defined(__GNUC__) || defined(__clang__)
385 # define MOZ_MAYBE_UNUSED __attribute__((__unused__))
386 #elif defined(_MSC_VER)
387 # define MOZ_MAYBE_UNUSED __pragma(warning(suppress : 4505))
388 #else
389 # define MOZ_MAYBE_UNUSED
390 #endif
392 /*
393 * MOZ_NO_STACK_PROTECTOR, specified at the start of a function declaration,
394 * indicates that the given function should *NOT* be instrumented to detect
395 * stack buffer overflows at runtime. (The function definition does not need to
396 * be annotated.)
397 *
398 * MOZ_NO_STACK_PROTECTOR int foo();
399 *
400 * Detecting stack buffer overflows at runtime is a security feature. This
401 * modifier should thus only be used on functions which are provably exempt of
402 * stack buffer overflows, for example because they do not use stack buffers.
403 *
404 * This modifier does not affect the corresponding function's linking behavior.
405 */
406 #if defined(MOZ_HAVE_NO_STACK_PROTECTOR)
407 # define MOZ_NO_STACK_PROTECTOR MOZ_HAVE_NO_STACK_PROTECTOR
408 #else
410 #endif
412 #ifdef __cplusplus
414 /**
415 * C++11 lets unions contain members that have non-trivial special member
416 * functions (default/copy/move constructor, copy/move assignment operator,
417 * destructor) if the user defines the corresponding functions on the union.
418 * (Such user-defined functions must rely on external knowledge about which arm
419 * is active to be safe. Be extra-careful defining these functions!)
420 *
421 * MSVC unfortunately warns/errors for this bog-standard C++11 pattern. Use
422 * these macro-guards around such member functions to disable the warnings:
423 *
424 * union U
425 * {
426 * std::string s;
427 * int x;
428 *
429 * MOZ_PUSH_DISABLE_NONTRIVIAL_UNION_WARNINGS
430 *
431 * // |U| must have a user-defined default constructor because |std::string|
432 * // has a non-trivial default constructor.
433 * U() ... { ... }
434 *
435 * // |U| must have a user-defined destructor because |std::string| has a
436 * // non-trivial destructor.
437 * ~U() { ... }
438 *
439 * MOZ_POP_DISABLE_NONTRIVIAL_UNION_WARNINGS
440 * };
441 */
442 # if defined(_MSC_VER)
443 # define MOZ_PUSH_DISABLE_NONTRIVIAL_UNION_WARNINGS \
444 __pragma(warning(push)) __pragma(warning(disable : 4582)) \
445 __pragma(warning(disable : 4583))
446 # define MOZ_POP_DISABLE_NONTRIVIAL_UNION_WARNINGS __pragma(warning(pop))
447 # else
450 # endif
452 /*
453 * The following macros are attributes that support the static analysis plugin
454 * included with Mozilla, and will be implemented (when such support is enabled)
455 * as C++11 attributes. Since such attributes are legal pretty much everywhere
456 * and have subtly different semantics depending on their placement, the
457 * following is a guide on where to place the attributes.
458 *
459 * Attributes that apply to a struct or class precede the name of the class:
460 * (Note that this is different from the placement of final for classes!)
461 *
462 * class MOZ_CLASS_ATTRIBUTE SomeClass {};
463 *
464 * Attributes that apply to functions follow the parentheses and const
465 * qualifiers but precede final, override and the function body:
466 *
467 * void DeclaredFunction() MOZ_FUNCTION_ATTRIBUTE;
468 * void SomeFunction() MOZ_FUNCTION_ATTRIBUTE {}
469 * void PureFunction() const MOZ_FUNCTION_ATTRIBUTE = 0;
470 * void OverriddenFunction() MOZ_FUNCTION_ATTIRBUTE override;
471 *
472 * Attributes that apply to variables or parameters follow the variable's name:
473 *
474 * int variable MOZ_VARIABLE_ATTRIBUTE;
475 *
476 * Attributes that apply to types follow the type name:
477 *
478 * typedef int MOZ_TYPE_ATTRIBUTE MagicInt;
479 * int MOZ_TYPE_ATTRIBUTE someVariable;
480 * int* MOZ_TYPE_ATTRIBUTE magicPtrInt;
481 * int MOZ_TYPE_ATTRIBUTE* ptrToMagicInt;
482 *
483 * Attributes that apply to statements precede the statement:
484 *
485 * MOZ_IF_ATTRIBUTE if (x == 0)
486 * MOZ_DO_ATTRIBUTE do { } while (0);
487 *
488 * Attributes that apply to labels precede the label:
489 *
490 * MOZ_LABEL_ATTRIBUTE target:
491 * goto target;
492 * MOZ_CASE_ATTRIBUTE case 5:
493 * MOZ_DEFAULT_ATTRIBUTE default:
494 *
495 * The static analyses that are performed by the plugin are as follows:
496 *
497 * MOZ_CAN_RUN_SCRIPT: Applies to functions which can run script. Callers of
498 * this function must also be marked as MOZ_CAN_RUN_SCRIPT, and all refcounted
499 * arguments must be strongly held in the caller. Note that MOZ_CAN_RUN_SCRIPT
500 * should only be applied to function declarations, not definitions. If you
501 * need to apply it to a definition (eg because both are generated by a macro)
502 * use MOZ_CAN_RUN_SCRIPT_FOR_DEFINITION.
503 *
504 * MOZ_CAN_RUN_SCRIPT can be applied to XPIDL-generated declarations by
505 * annotating the method or attribute as [can_run_script] in the .idl file.
506 *
507 * MOZ_CAN_RUN_SCRIPT_FOR_DEFINITION: Same as MOZ_CAN_RUN_SCRIPT, but usable on
508 * a definition. If the declaration is in a header file, users of that header
509 * file may not see the annotation.
510 * MOZ_CAN_RUN_SCRIPT_BOUNDARY: Applies to functions which need to call
511 * MOZ_CAN_RUN_SCRIPT functions, but should not themselves be considered
512 * MOZ_CAN_RUN_SCRIPT. This should generally be avoided but can be used in
513 * two cases:
514 * 1) As a temporary measure to limit the scope of changes when adding
515 * MOZ_CAN_RUN_SCRIPT. Such a use must be accompanied by a follow-up bug
516 * to replace the MOZ_CAN_RUN_SCRIPT_BOUNDARY with MOZ_CAN_RUN_SCRIPT and
517 * a comment linking to that bug.
518 * 2) If we can reason that the MOZ_CAN_RUN_SCRIPT callees of the function
519 * do not in fact run script (for example, because their behavior depends
520 * on arguments and we pass the arguments that don't allow script
521 * execution). Such a use must be accompanied by a comment that explains
522 * why it's OK to have the MOZ_CAN_RUN_SCRIPT_BOUNDARY, as well as
523 * comments in the callee pointing out that if its behavior changes the
524 * caller might need adjusting. And perhaps also a followup bug to
525 * refactor things so the "script" and "no script" codepaths do not share
526 * a chokepoint.
527 * Importantly, any use MUST be accompanied by a comment explaining why it's
528 * there, and should ideally have an action plan for getting rid of the
529 * MOZ_CAN_RUN_SCRIPT_BOUNDARY annotation.
530 * MOZ_MUST_OVERRIDE: Applies to all C++ member functions. All immediate
531 * subclasses must provide an exact override of this method; if a subclass
532 * does not override this method, the compiler will emit an error. This
533 * attribute is not limited to virtual methods, so if it is applied to a
534 * nonvirtual method and the subclass does not provide an equivalent
535 * definition, the compiler will emit an error.
536 * MOZ_STATIC_CLASS: Applies to all classes. Any class with this annotation is
537 * expected to live in static memory, so it is a compile-time error to use
538 * it, or an array of such objects, as the type of a variable declaration, or
539 * as a temporary object, or as the type of a new expression (unless
540 * placement new is being used). If a member of another class uses this
541 * class, or if another class inherits from this class, then it is considered
542 * to be a static class as well, although this attribute need not be provided
543 * in such cases.
544 * MOZ_STATIC_LOCAL_CLASS: Applies to all classes. Any class with this
545 * annotation is expected to be a static local variable, so it is
546 * a compile-time error to use it, or an array of such objects, or as a
547 * temporary object, or as the type of a new expression. If another class
548 * inherits from this class then it is considered to be a static local
549 * class as well, although this attribute need not be provided in such cases.
550 * It is also a compile-time error for any class with this annotation to have
551 * a non-trivial destructor.
552 * MOZ_STACK_CLASS: Applies to all classes. Any class with this annotation is
553 * expected to live on the stack, so it is a compile-time error to use it, or
554 * an array of such objects, as a global or static variable, or as the type of
555 * a new expression (unless placement new is being used). If a member of
556 * another class uses this class, or if another class inherits from this
557 * class, then it is considered to be a stack class as well, although this
558 * attribute need not be provided in such cases.
559 * MOZ_NONHEAP_CLASS: Applies to all classes. Any class with this annotation is
560 * expected to live on the stack or in static storage, so it is a compile-time
561 * error to use it, or an array of such objects, as the type of a new
562 * expression. If a member of another class uses this class, or if another
563 * class inherits from this class, then it is considered to be a non-heap
564 * class as well, although this attribute need not be provided in such cases.
565 * MOZ_HEAP_CLASS: Applies to all classes. Any class with this annotation is
566 * expected to live on the heap, so it is a compile-time error to use it, or
567 * an array of such objects, as the type of a variable declaration, or as a
568 * temporary object. If a member of another class uses this class, or if
569 * another class inherits from this class, then it is considered to be a heap
570 * class as well, although this attribute need not be provided in such cases.
571 * MOZ_NON_TEMPORARY_CLASS: Applies to all classes. Any class with this
572 * annotation is expected not to live in a temporary. If a member of another
573 * class uses this class or if another class inherits from this class, then it
574 * is considered to be a non-temporary class as well, although this attribute
575 * need not be provided in such cases.
576 * MOZ_TEMPORARY_CLASS: Applies to all classes. Any class with this annotation
577 * is expected to only live in a temporary. If another class inherits from
578 * this class, then it is considered to be a non-temporary class as well,
579 * although this attribute need not be provided in such cases.
580 * MOZ_RAII: Applies to all classes. Any class with this annotation is assumed
581 * to be a RAII guard, which is expected to live on the stack in an automatic
582 * allocation. It is prohibited from being allocated in a temporary, static
583 * storage, or on the heap. This is a combination of MOZ_STACK_CLASS and
584 * MOZ_NON_TEMPORARY_CLASS.
585 * MOZ_ONLY_USED_TO_AVOID_STATIC_CONSTRUCTORS: Applies to all classes that are
586 * intended to prevent introducing static initializers. This attribute
587 * currently makes it a compile-time error to instantiate these classes
588 * anywhere other than at the global scope, or as a static member of a class.
589 * In non-debug mode, it also prohibits non-trivial constructors and
590 * destructors.
591 * MOZ_TRIVIAL_CTOR_DTOR: Applies to all classes that must have both a trivial
592 * or constexpr constructor and a trivial destructor. Setting this attribute
593 * on a class makes it a compile-time error for that class to get a
594 * non-trivial constructor or destructor for any reason.
595 * MOZ_ALLOW_TEMPORARY: Applies to constructors. This indicates that using the
596 * constructor is allowed in temporary expressions, if it would have otherwise
597 * been forbidden by the type being a MOZ_NON_TEMPORARY_CLASS. Useful for
598 * constructors like Maybe(Nothing).
599 * MOZ_HEAP_ALLOCATOR: Applies to any function. This indicates that the return
600 * value is allocated on the heap, and will as a result check such allocations
601 * during MOZ_STACK_CLASS and MOZ_NONHEAP_CLASS annotation checking.
602 * MOZ_IMPLICIT: Applies to constructors. Implicit conversion constructors
603 * are disallowed by default unless they are marked as MOZ_IMPLICIT. This
604 * attribute must be used for constructors which intend to provide implicit
605 * conversions.
606 * MOZ_IS_REFPTR: Applies to class declarations of ref pointer to mark them as
607 * such for use with static-analysis.
608 * A ref pointer is an object wrapping a pointer and automatically taking care
609 * of its refcounting upon construction/destruction/transfer of ownership.
610 * This annotation implies MOZ_IS_SMARTPTR_TO_REFCOUNTED.
611 * MOZ_IS_SMARTPTR_TO_REFCOUNTED: Applies to class declarations of smart
612 * pointers to ref counted classes to mark them as such for use with
613 * static-analysis.
614 * MOZ_NO_ARITHMETIC_EXPR_IN_ARGUMENT: Applies to functions. Makes it a compile
615 * time error to pass arithmetic expressions on variables to the function.
616 * MOZ_OWNING_REF: Applies to declarations of pointers to reference counted
617 * types. This attribute tells the compiler that the raw pointer is a strong
618 * reference, where ownership through methods such as AddRef and Release is
619 * managed manually. This can make the compiler ignore these pointers when
620 * validating the usage of pointers otherwise.
621 *
622 * Example uses include owned pointers inside of unions, and pointers stored
623 * in POD types where a using a smart pointer class would make the object
624 * non-POD.
625 * MOZ_NON_OWNING_REF: Applies to declarations of pointers to reference counted
626 * types. This attribute tells the compiler that the raw pointer is a weak
627 * reference, which is ensured to be valid by a guarantee that the reference
628 * will be nulled before the pointer becomes invalid. This can make the
629 * compiler ignore these pointers when validating the usage of pointers
630 * otherwise.
631 *
632 * Examples include an mOwner pointer, which is nulled by the owning class's
633 * destructor, and is null-checked before dereferencing.
634 * MOZ_UNSAFE_REF: Applies to declarations of pointers to reference counted
635 * types. Occasionally there are non-owning references which are valid, but
636 * do not take the form of a MOZ_NON_OWNING_REF. Their safety may be
637 * dependent on the behaviour of API consumers. The string argument passed
638 * to this macro documents the safety conditions. This can make the compiler
639 * ignore these pointers when validating the usage of pointers elsewhere.
640 *
641 * Examples include an nsAtom* member which is known at compile time to point
642 * to a static atom which is valid throughout the lifetime of the program, or
643 * an API which stores a pointer, but doesn't take ownership over it, instead
644 * requiring the API consumer to correctly null the value before it becomes
645 * invalid.
646 *
647 * Use of this annotation is discouraged when a strong reference or one of
648 * the above two annotations can be used instead.
649 * MOZ_NO_ADDREF_RELEASE_ON_RETURN: Applies to function declarations. Makes it
650 * a compile time error to call AddRef or Release on the return value of a
651 * function. This is intended to be used with operator->() of our smart
652 * pointer classes to ensure that the refcount of an object wrapped in a
653 * smart pointer is not manipulated directly.
654 * MOZ_NEEDS_NO_VTABLE_TYPE: Applies to template class declarations. Makes it
655 * a compile time error to instantiate this template with a type parameter
656 * which has a VTable.
657 * MOZ_NON_MEMMOVABLE: Applies to class declarations for types that are not safe
658 * to be moved in memory using memmove().
659 * MOZ_NEEDS_MEMMOVABLE_TYPE: Applies to template class declarations where the
660 * template arguments are required to be safe to move in memory using
661 * memmove(). Passing MOZ_NON_MEMMOVABLE types to these templates is a
662 * compile time error.
663 * MOZ_NEEDS_MEMMOVABLE_MEMBERS: Applies to class declarations where each member
664 * must be safe to move in memory using memmove(). MOZ_NON_MEMMOVABLE types
665 * used in members of these classes are compile time errors.
666 * MOZ_NO_DANGLING_ON_TEMPORARIES: Applies to method declarations which return
667 * a pointer that is freed when the destructor of the class is called. This
668 * prevents these methods from being called on temporaries of the class,
669 * reducing risks of use-after-free.
670 * This attribute cannot be applied to && methods.
671 * In some cases, adding a deleted &&-qualified overload is too restrictive as
672 * this method should still be callable as a non-escaping argument to another
673 * function. This annotation can be used in those cases.
674 * MOZ_INHERIT_TYPE_ANNOTATIONS_FROM_TEMPLATE_ARGS: Applies to template class
675 * declarations where an instance of the template should be considered, for
676 * static analysis purposes, to inherit any type annotations (such as
677 * MOZ_STACK_CLASS) from its template arguments.
678 * MOZ_INIT_OUTSIDE_CTOR: Applies to class member declarations. Occasionally
679 * there are class members that are not initialized in the constructor,
680 * but logic elsewhere in the class ensures they are initialized prior to use.
681 * Using this attribute on a member disables the check that this member must
682 * be initialized in constructors via list-initialization, in the constructor
683 * body, or via functions called from the constructor body.
684 * MOZ_IS_CLASS_INIT: Applies to class method declarations. Occasionally the
685 * constructor doesn't initialize all of the member variables and another
686 * function is used to initialize the rest. This marker is used to make the
687 * static analysis tool aware that the marked function is part of the
688 * initialization process and to include the marked function in the scan
689 * mechanism that determines which member variables still remain
690 * uninitialized.
691 * MOZ_NON_PARAM: Applies to types. Makes it compile time error to use the type
692 * in parameter without pointer or reference.
693 * MOZ_NON_AUTOABLE: Applies to class declarations. Makes it a compile time
694 * error to use `auto` in place of this type in variable declarations. This
695 * is intended to be used with types which are intended to be implicitly
696 * constructed into other other types before being assigned to variables.
697 * MOZ_REQUIRED_BASE_METHOD: Applies to virtual class method declarations.
698 * Sometimes derived classes override methods that need to be called by their
699 * overridden counterparts. This marker indicates that the marked method must
700 * be called by the method that it overrides.
701 * MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG: Applies to method declarations.
702 * Callers of the annotated method must return from that function within the
703 * calling block using an explicit `return` statement if the "this" value for
704 * the call is a parameter of the caller. Only calls to Constructors,
705 * references to local and member variables, and calls to functions or
706 * methods marked as MOZ_MAY_CALL_AFTER_MUST_RETURN may be made after the
707 * MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG call.
708 * MOZ_MAY_CALL_AFTER_MUST_RETURN: Applies to function or method declarations.
709 * Calls to these methods may be made in functions after calls a
710 * MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG method.
711 * MOZ_LIFETIME_BOUND: Applies to method declarations.
712 * The result of calling these functions on temporaries may not be returned as
713 * a reference or bound to a reference variable.
714 * MOZ_UNANNOTATED/MOZ_ANNOTATED: Applies to Mutexes/Monitors and variations on
715 * them. MOZ_UNANNOTATED indicates that the Mutex/Monitor/etc hasn't been
716 * examined and annotated using macros from mfbt/ThreadSafety --
717 * MOZ_GUARDED_BY()/REQUIRES()/etc. MOZ_ANNOTATED is used in rare cases to
718 * indicate that is has been looked at, but it did not need any
719 * MOZ_GUARDED_BY()/REQUIRES()/etc (and thus static analysis knows it can
720 * ignore this Mutex/Monitor/etc)
721 */
723 // gcc emits a nuisance warning -Wignored-attributes because attributes do not
724 // affect mangled names, and therefore template arguments do not propagate
725 // their attributes. It is rare that this would affect anything in practice,
726 // and most compilers are silent about it. Similarly, -Wattributes complains
727 // about attributes being ignored during template instantiation.
728 //
729 // Be conservative and only suppress the warning when running in a
730 // configuration where it would be emitted, namely when compiling with the
731 // XGILL_PLUGIN for the rooting hazard analysis (which runs under gcc.) If we
732 // end up wanting these attributes in general GCC builds, change this to
733 // something like
734 //
735 // #if defined(__GNUC__) && ! defined(__clang__)
736 //
737 # ifdef XGILL_PLUGIN
740 # endif
742 # if defined(MOZ_CLANG_PLUGIN) || defined(XGILL_PLUGIN)
744 # define MOZ_CAN_RUN_SCRIPT_FOR_DEFINITION \
747 # define MOZ_CAN_RUN_SCRIPT_BOUNDARY \
751 # define MOZ_STATIC_LOCAL_CLASS \
757 # define MOZ_NON_TEMPORARY_CLASS \
760 # define MOZ_TRIVIAL_CTOR_DTOR \
763 # ifdef DEBUG
764 /* in debug builds, these classes do have non-trivial constructors. */
765 # define MOZ_ONLY_USED_TO_AVOID_STATIC_CONSTRUCTORS \
767 # else
768 # define MOZ_ONLY_USED_TO_AVOID_STATIC_CONSTRUCTORS \
770 # endif
772 # define MOZ_IS_SMARTPTR_TO_REFCOUNTED \
774 # define MOZ_IS_REFPTR MOZ_IS_SMARTPTR_TO_REFCOUNTED
775 # define MOZ_NO_ARITHMETIC_EXPR_IN_ARGUMENT \
780 # define MOZ_NO_ADDREF_RELEASE_ON_RETURN \
782 # define MOZ_NEEDS_NO_VTABLE_TYPE \
785 # define MOZ_NEEDS_MEMMOVABLE_TYPE \
787 # define MOZ_NEEDS_MEMMOVABLE_MEMBERS \
789 # define MOZ_NO_DANGLING_ON_TEMPORARIES \
791 # define MOZ_INHERIT_TYPE_ANNOTATIONS_FROM_TEMPLATE_ARGS \
792 __attribute__(( \
795 # define MOZ_INIT_OUTSIDE_CTOR
796 # define MOZ_IS_CLASS_INIT
798 # define MOZ_REQUIRED_BASE_METHOD \
800 # define MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG \
802 # define MOZ_MAY_CALL_AFTER_MUST_RETURN \
806 # ifndef XGILL_PLUGIN
809 # else
812 # endif
814 /*
815 * It turns out that clang doesn't like void func() __attribute__ {} without a
816 * warning, so use pragmas to disable the warning.
817 */
818 # ifdef __clang__
819 # define MOZ_HEAP_ALLOCATOR \
824 # else
826 # endif
827 # else
870 # define MOZ_RAII MOZ_NON_TEMPORARY_CLASS MOZ_STACK_CLASS
872 // XGILL_PLUGIN is used for the GC rooting hazard analysis, which compiles with
873 // gcc. gcc has different rules governing __attribute__((...)) placement, so
874 // some attributes will error out when used in the source code where clang
875 // expects them to be. Remove the problematic annotations when needed.
876 //
877 // The placement of c++11 [[...]] attributes is more flexible and defined by a
878 // spec, so it would be nice to switch to those for the problematic
879 // cases. Unfortunately, the official spec provides *no* way to annotate a
880 // lambda function, which is one source of the difficulty here. It appears that
881 // this will be fixed in c++23: https://github.com/cplusplus/papers/issues/882
883 # ifdef XGILL_PLUGIN
885 # undef MOZ_MUST_OVERRIDE
886 # undef MOZ_CAN_RUN_SCRIPT_FOR_DEFINITION
887 # undef MOZ_CAN_RUN_SCRIPT
888 # undef MOZ_CAN_RUN_SCRIPT_BOUNDARY
894 # endif
898 /**
899 * Printf style formats. MOZ_FORMAT_PRINTF and MOZ_FORMAT_WPRINTF can be used
900 * to annotate a function or method that is "printf/wprintf-like"; this will let
901 * (some) compilers check that the arguments match the template string.
902 *
903 * This macro takes two arguments. The first argument is the argument
904 * number of the template string. The second argument is the argument
905 * number of the '...' argument holding the arguments.
906 *
907 * Argument numbers start at 1. Note that the implicit "this"
908 * argument of a non-static member function counts as an argument.
909 *
910 * So, for a simple case like:
911 * void print_something (int whatever, const char *fmt, ...);
912 * The corresponding annotation would be
913 * MOZ_FORMAT_PRINTF(2, 3)
914 * However, if "print_something" were a non-static member function,
915 * then the annotation would be:
916 * MOZ_FORMAT_PRINTF(3, 4)
917 *
918 * The second argument should be 0 for vprintf-like functions; that
919 * is, those taking a va_list argument.
920 *
921 * Note that the checking is limited to standards-conforming
922 * printf-likes, and in particular this should not be used for
923 * PR_snprintf and friends, which are "printf-like" but which assign
924 * different meanings to the various formats.
925 *
926 * MinGW requires special handling due to different format specifiers
927 * on different platforms. The macro __MINGW_PRINTF_FORMAT maps to
928 * either gnu_printf or ms_printf depending on where we are compiling
929 * to avoid warnings on format specifiers that are legal.
930 *
931 * At time of writing MinGW has no wide equivalent to __MINGW_PRINTF_FORMAT;
932 * therefore __MINGW_WPRINTF_FORMAT has been implemented following the same
933 * pattern seen in MinGW's source.
934 */
935 #ifdef __MINGW32__
936 # define MOZ_FORMAT_PRINTF(stringIndex, firstToCheck) \
937 __attribute__((format(__MINGW_PRINTF_FORMAT, stringIndex, firstToCheck)))
938 # ifndef __MINGW_WPRINTF_FORMAT
939 # if defined(__clang__)
940 # define __MINGW_WPRINTF_FORMAT wprintf
941 # elif defined(_UCRT) || __USE_MINGW_ANSI_STDIO
942 # define __MINGW_WPRINTF_FORMAT gnu_wprintf
943 # else
944 # define __MINGW_WPRINTF_FORMAT ms_wprintf
945 # endif
946 # endif
947 # define MOZ_FORMAT_WPRINTF(stringIndex, firstToCheck) \
948 __attribute__((format(__MINGW_WPRINTF_FORMAT, stringIndex, firstToCheck)))
949 #elif __GNUC__ || __clang__
950 # define MOZ_FORMAT_PRINTF(stringIndex, firstToCheck) \
951 __attribute__((format(printf, stringIndex, firstToCheck)))
952 # define MOZ_FORMAT_WPRINTF(stringIndex, firstToCheck) \
953 __attribute__((format(wprintf, stringIndex, firstToCheck)))
954 #else
955 # define MOZ_FORMAT_PRINTF(stringIndex, firstToCheck)
956 # define MOZ_FORMAT_WPRINTF(stringIndex, firstToCheck)
957 #endif
959 /**
960 * To manually declare an XPCOM ABI-compatible virtual function, the following
961 * macros can be used to handle the non-standard ABI used on Windows for COM
962 * compatibility. E.g.:
963 *
964 * virtual ReturnType MOZ_XPCOM_ABI foo();
965 */
966 #if defined(XP_WIN)
967 # define MOZ_XPCOM_ABI __stdcall
968 #else
969 # define MOZ_XPCOM_ABI
970 #endif
972 /**
973 * MSVC / clang-cl don't optimize empty bases correctly unless we explicitly
974 * tell it to, see:
975 *
976 * https://stackoverflow.com/questions/12701469/why-is-the-empty-base-class-optimization-ebo-is-not-working-in-msvc
977 * https://devblogs.microsoft.com/cppblog/optimizing-the-layout-of-empty-base-classes-in-vs2015-update-2-3/
978 */
979 #if defined(_MSC_VER)
980 # define MOZ_EMPTY_BASES __declspec(empty_bases)
981 #else
982 # define MOZ_EMPTY_BASES
983 #endif