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/. */
6
7 #ifndef js_GCAnnotations_h
8 #define js_GCAnnotations_h
9
10 // Set of annotations for the rooting hazard analysis, used to categorize types
11 // and functions.
12 #ifdef XGILL_PLUGIN
13
14 # define JS_EXPECT_HAZARDS __attribute__((annotate("Expect Hazards")))
15
16 // Mark a type as being a GC thing (eg js::gc::Cell has this annotation).
17 # define JS_HAZ_GC_THING __attribute__((annotate("GC Thing")))
18
19 // Mark a type as holding a pointer to a GC thing (eg JS::Value has this
20 // annotation.) "Inherited" by templatized types with
21 // MOZ_INHERIT_TYPE_ANNOTATIONS_FROM_TEMPLATE_ARGS.
22 # define JS_HAZ_GC_POINTER __attribute__((annotate("GC Pointer")))
23
24 // Mark a type as a rooted pointer, suitable for use on the stack (eg all
25 // Rooted<T> instantiations should have this.) "Inherited" by templatized types
26 // with MOZ_INHERIT_TYPE_ANNOTATIONS_FROM_TEMPLATE_ARGS.
27 # define JS_HAZ_ROOTED __attribute__((annotate("Rooted Pointer")))
28
29 // Mark a type as something that should not be held live across a GC, but which
30 // is not itself a GC pointer. Note that this property is *not* inherited by
31 // templatized types with MOZ_INHERIT_TYPE_ANNOTATIONS_FROM_TEMPLATE_ARGS.
32 # define JS_HAZ_GC_INVALIDATED __attribute__((annotate("Invalidated by GC")))
33
34 // Mark a class as a base class of rooted types, eg CustomAutoRooter. All
35 // descendants of this class will be considered rooted, though classes that
36 // merely contain these as a field member will not be. "Inherited" by
37 // templatized types with MOZ_INHERIT_TYPE_ANNOTATIONS_FROM_TEMPLATE_ARGS
38 # define JS_HAZ_ROOTED_BASE __attribute__((annotate("Rooted Base")))
39
40 // Mark a type that would otherwise be considered a GC Pointer (eg because it
41 // contains a JS::Value field) as a non-GC pointer. It is handled almost the
42 // same in the analysis as a rooted pointer, except it will not be reported as
43 // an unnecessary root if used across a GC call. This should rarely be used,
44 // but makes sense for something like ErrorResult, which only contains a GC
45 // pointer when it holds an exception (and it does its own rooting,
46 // conditionally.)
47 # define JS_HAZ_NON_GC_POINTER \
48 __attribute__((annotate("Suppressed GC Pointer")))
49
50 // Mark a function as something that runs a garbage collection, potentially
51 // invalidating GC pointers.
52 # define JS_HAZ_GC_CALL __attribute__((annotate("GC Call")))
53
54 // Mark an RAII class as suppressing GC within its scope.
55 # define JS_HAZ_GC_SUPPRESSED __attribute__((annotate("Suppress GC")))
56
57 // Mark a function as one that can run script if called. This obviously
58 // subsumes JS_HAZ_GC_CALL, since anything that can run script can GC.`
59 # define JS_HAZ_CAN_RUN_SCRIPT __attribute__((annotate("Can run script")))
60
61 // Mark a function as able to call JSNatives. Otherwise, JSNatives don't show
62 // up in the callgraph. This doesn't matter for the can-GC analysis, but it is
63 // very nice for other uses of the callgraph.
64 # define JS_HAZ_JSNATIVE_CALLER __attribute__((annotate("Calls JSNatives")))
65
66 // Mark a variable as being "GC safe", i.e., it does not contain any
67 // invalidatable pointers at the current point in the code. A typical
68 // example might be a collection containing GC pointers, which at the
69 // present time is empty. This property is only temporary; the next use
70 // of the variable will invalidate it (on the assumption that a GC pointer
71 // might be added to it.) Try to use this as early as possible, probably
72 // immediately after construction, so that if future mutations through
73 // the variable are added, they won't be covered by the annotation.
74 # define JS_HAZ_VALUE_IS_GC_SAFE(var) JS::detail::MarkVariableAsGCSafe(var)
75
76 #else
77
78 # define JS_EXPECT_HAZARDS
79 # define JS_HAZ_GC_THING
80 # define JS_HAZ_GC_POINTER
81 # define JS_HAZ_ROOTED
82 # define JS_HAZ_GC_INVALIDATED
83 # define JS_HAZ_ROOTED_BASE
84 # define JS_HAZ_NON_GC_POINTER
85 # define JS_HAZ_GC_CALL
86 # define JS_HAZ_GC_SUPPRESSED
87 # define JS_HAZ_CAN_RUN_SCRIPT
88 # define JS_HAZ_JSNATIVE_CALLER
89 # define JS_HAZ_VALUE_IS_GC_SAFE(var)
90
91 #endif
92
93 #ifdef XGILL_PLUGIN
94
95 // Implemented by passing variable to a dummy function so that it shows up
96 // in the control flow graph.
97 namespace JS {
98 namespace detail {
99
100 template <typename T>
MarkVariableAsGCSafe(T & var)101 static inline void MarkVariableAsGCSafe(T& var) {
102 asm("");
103 }
104
105 } // namespace detail
106 } // namespace JS
107
108 #endif
109
110 #endif /* js_GCAnnotations_h */
111