Line data Source code
1 : //===- llvm/CodeGen/GCStrategy.h - Garbage collection -----------*- C++ -*-===//
2 : //
3 : // The LLVM Compiler Infrastructure
4 : //
5 : // This file is distributed under the University of Illinois Open Source
6 : // License. See LICENSE.TXT for details.
7 : //
8 : //===----------------------------------------------------------------------===//
9 : //
10 : // GCStrategy coordinates code generation algorithms and implements some itself
11 : // in order to generate code compatible with a target code generator as
12 : // specified in a function's 'gc' attribute. Algorithms are enabled by setting
13 : // flags in a subclass's constructor, and some virtual methods can be
14 : // overridden.
15 : //
16 : // GCStrategy is relevant for implementations using either gc.root or
17 : // gc.statepoint based lowering strategies, but is currently focused mostly on
18 : // options for gc.root. This will change over time.
19 : //
20 : // When requested by a subclass of GCStrategy, the gc.root implementation will
21 : // populate GCModuleInfo and GCFunctionInfo with that about each Function in
22 : // the Module that opts in to garbage collection. Specifically:
23 : //
24 : // - Safe points
25 : // Garbage collection is generally only possible at certain points in code.
26 : // GCStrategy can request that the collector insert such points:
27 : //
28 : // - At and after any call to a subroutine
29 : // - Before returning from the current function
30 : // - Before backwards branches (loops)
31 : //
32 : // - Roots
33 : // When a reference to a GC-allocated object exists on the stack, it must be
34 : // stored in an alloca registered with llvm.gcoot.
35 : //
36 : // This information can used to emit the metadata tables which are required by
37 : // the target garbage collector runtime.
38 : //
39 : // When used with gc.statepoint, information about safepoint and roots can be
40 : // found in the binary StackMap section after code generation. Safepoint
41 : // placement is currently the responsibility of the frontend, though late
42 : // insertion support is planned. gc.statepoint does not currently support
43 : // custom stack map formats; such can be generated by parsing the standard
44 : // stack map section if desired.
45 : //
46 : // The read and write barrier support can be used with either implementation.
47 : //
48 : //===----------------------------------------------------------------------===//
49 :
50 : #ifndef LLVM_CODEGEN_GCSTRATEGY_H
51 : #define LLVM_CODEGEN_GCSTRATEGY_H
52 :
53 : #include "llvm/ADT/None.h"
54 : #include "llvm/ADT/Optional.h"
55 : #include "llvm/Support/Registry.h"
56 : #include <string>
57 :
58 : namespace llvm {
59 :
60 : class Type;
61 :
62 : namespace GC {
63 :
64 : /// PointKind - Used to indicate whether the address of the call instruction
65 : /// or the address after the call instruction is listed in the stackmap. For
66 : /// most runtimes, PostCall safepoints are appropriate.
67 : ///
68 : enum PointKind {
69 : PreCall, ///< Instr is a call instruction.
70 : PostCall ///< Instr is the return address of a call.
71 : };
72 :
73 : } // end namespace GC
74 :
75 : /// GCStrategy describes a garbage collector algorithm's code generation
76 : /// requirements, and provides overridable hooks for those needs which cannot
77 : /// be abstractly described. GCStrategy objects must be looked up through
78 : /// the Function. The objects themselves are owned by the Context and must
79 : /// be immutable.
80 50 : class GCStrategy {
81 : private:
82 : friend class GCModuleInfo;
83 :
84 : std::string Name;
85 :
86 : protected:
87 : bool UseStatepoints = false; /// Uses gc.statepoints as opposed to gc.roots,
88 : /// if set, none of the other options can be
89 : /// anything but their default values.
90 :
91 : unsigned NeededSafePoints = 0; ///< Bitmask of required safe points.
92 : bool CustomReadBarriers = false; ///< Default is to insert loads.
93 : bool CustomWriteBarriers = false; ///< Default is to insert stores.
94 : bool CustomRoots = false; ///< Default is to pass through to backend.
95 : bool InitRoots= true; ///< If set, roots are nulled during lowering.
96 : bool UsesMetadata = false; ///< If set, backend must emit metadata tables.
97 :
98 : public:
99 : GCStrategy();
100 0 : virtual ~GCStrategy() = default;
101 :
102 : /// Return the name of the GC strategy. This is the value of the collector
103 : /// name string specified on functions which use this strategy.
104 18 : const std::string &getName() const { return Name; }
105 :
106 : /// By default, write barriers are replaced with simple store
107 : /// instructions. If true, you must provide a custom pass to lower
108 : /// calls to \@llvm.gcwrite.
109 0 : bool customWriteBarrier() const { return CustomWriteBarriers; }
110 :
111 : /// By default, read barriers are replaced with simple load
112 : /// instructions. If true, you must provide a custom pass to lower
113 : /// calls to \@llvm.gcread.
114 0 : bool customReadBarrier() const { return CustomReadBarriers; }
115 :
116 : /// Returns true if this strategy is expecting the use of gc.statepoints,
117 : /// and false otherwise.
118 : bool useStatepoints() const { return UseStatepoints; }
119 :
120 : /** @name Statepoint Specific Properties */
121 : ///@{
122 :
123 : /// If the type specified can be reliably distinguished, returns true for
124 : /// pointers to GC managed locations and false for pointers to non-GC
125 : /// managed locations. Note a GCStrategy can always return 'None' (i.e. an
126 : /// empty optional indicating it can't reliably distinguish.
127 0 : virtual Optional<bool> isGCManagedPointer(const Type *Ty) const {
128 0 : return None;
129 : }
130 : ///@}
131 :
132 : /** @name GCRoot Specific Properties
133 : * These properties and overrides only apply to collector strategies using
134 : * GCRoot.
135 : */
136 : ///@{
137 :
138 : /// True if safe points of any kind are required. By default, none are
139 : /// recorded.
140 0 : bool needsSafePoints() const { return NeededSafePoints != 0; }
141 :
142 : /// True if the given kind of safe point is required. By default, none are
143 : /// recorded.
144 0 : bool needsSafePoint(GC::PointKind Kind) const {
145 4 : return (NeededSafePoints & 1 << Kind) != 0;
146 : }
147 :
148 : /// By default, roots are left for the code generator so it can generate a
149 : /// stack map. If true, you must provide a custom pass to lower
150 : /// calls to \@llvm.gcroot.
151 : bool customRoots() const { return CustomRoots; }
152 :
153 : /// If set, gcroot intrinsics should initialize their allocas to null
154 : /// before the first use. This is necessary for most GCs and is enabled by
155 : /// default.
156 0 : bool initializeRoots() const { return InitRoots; }
157 :
158 : /// If set, appropriate metadata tables must be emitted by the back-end
159 : /// (assembler, JIT, or otherwise). For statepoint, this method is
160 : /// currently unsupported. The stackmap information can be found in the
161 : /// StackMap section as described in the documentation.
162 0 : bool usesMetadata() const { return UsesMetadata; }
163 :
164 : ///@}
165 : };
166 :
167 : /// Subclasses of GCStrategy are made available for use during compilation by
168 : /// adding them to the global GCRegistry. This can done either within the
169 : /// LLVM source tree or via a loadable plugin. An example registeration
170 : /// would be:
171 : /// static GCRegistry::Add<CustomGC> X("custom-name",
172 : /// "my custom supper fancy gc strategy");
173 : ///
174 : /// Note that to use a custom GCMetadataPrinter w/gc.roots, you must also
175 : /// register your GCMetadataPrinter subclass with the
176 : /// GCMetadataPrinterRegistery as well.
177 : using GCRegistry = Registry<GCStrategy>;
178 :
179 : } // end namespace llvm
180 :
181 : #endif // LLVM_CODEGEN_GCSTRATEGY_H
|
