1 //===-- llvm/LLVMContext.h - Class for managing "global" state --*- 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 // This file declares LLVMContext, a container of "global" state in LLVM, such
11 // as the global type and constant uniquing tables.
12 //
13 //===----------------------------------------------------------------------===//
14
15 #ifndef LLVM_IR_LLVMCONTEXT_H
16 #define LLVM_IR_LLVMCONTEXT_H
17
18 #include "llvm/Support/CBindingWrapping.h"
19 #include "llvm/Support/Options.h"
20
21 namespace llvm {
22
23 class LLVMContextImpl;
24 class StringRef;
25 class Twine;
26 class Instruction;
27 class Module;
28 class MDString;
29 class DICompositeType;
30 class SMDiagnostic;
31 class DiagnosticInfo;
32 enum DiagnosticSeverity : char;
33 template <typename T> class SmallVectorImpl;
34 class Function;
35 class DebugLoc;
36 class OptBisect;
37
38 /// This is an important class for using LLVM in a threaded context. It
39 /// (opaquely) owns and manages the core "global" data of LLVM's core
40 /// infrastructure, including the type and constant uniquing tables.
41 /// LLVMContext itself provides no locking guarantees, so you should be careful
42 /// to have one context per thread.
43 class LLVMContext {
44 public:
45 LLVMContextImpl *const pImpl;
46 LLVMContext();
47 ~LLVMContext();
48
49 // Pinned metadata names, which always have the same value. This is a
50 // compile-time performance optimization, not a correctness optimization.
51 enum {
52 MD_dbg = 0, // "dbg"
53 MD_tbaa = 1, // "tbaa"
54 MD_prof = 2, // "prof"
55 MD_fpmath = 3, // "fpmath"
56 MD_range = 4, // "range"
57 MD_tbaa_struct = 5, // "tbaa.struct"
58 MD_invariant_load = 6, // "invariant.load"
59 MD_alias_scope = 7, // "alias.scope"
60 MD_noalias = 8, // "noalias",
61 MD_nontemporal = 9, // "nontemporal"
62 MD_mem_parallel_loop_access = 10, // "llvm.mem.parallel_loop_access"
63 MD_nonnull = 11, // "nonnull"
64 MD_dereferenceable = 12, // "dereferenceable"
65 MD_dereferenceable_or_null = 13, // "dereferenceable_or_null"
66 MD_make_implicit = 14, // "make.implicit"
67 MD_unpredictable = 15, // "unpredictable"
68 MD_invariant_group = 16, // "invariant.group"
69 MD_align = 17, // "align"
70 MD_loop = 18, // "llvm.loop"
71 MD_type = 19, // "type"
72 };
73
74 /// Known operand bundle tag IDs, which always have the same value. All
75 /// operand bundle tags that LLVM has special knowledge of are listed here.
76 /// Additionally, this scheme allows LLVM to efficiently check for specific
77 /// operand bundle tags without comparing strings.
78 enum {
79 OB_deopt = 0, // "deopt"
80 OB_funclet = 1, // "funclet"
81 OB_gc_transition = 2, // "gc-transition"
82 };
83
84 /// getMDKindID - Return a unique non-zero ID for the specified metadata kind.
85 /// This ID is uniqued across modules in the current LLVMContext.
86 unsigned getMDKindID(StringRef Name) const;
87
88 /// getMDKindNames - Populate client supplied SmallVector with the name for
89 /// custom metadata IDs registered in this LLVMContext.
90 void getMDKindNames(SmallVectorImpl<StringRef> &Result) const;
91
92 /// getOperandBundleTags - Populate client supplied SmallVector with the
93 /// bundle tags registered in this LLVMContext. The bundle tags are ordered
94 /// by increasing bundle IDs.
95 /// \see LLVMContext::getOperandBundleTagID
96 void getOperandBundleTags(SmallVectorImpl<StringRef> &Result) const;
97
98 /// getOperandBundleTagID - Maps a bundle tag to an integer ID. Every bundle
99 /// tag registered with an LLVMContext has an unique ID.
100 uint32_t getOperandBundleTagID(StringRef Tag) const;
101
102 /// Define the GC for a function
103 void setGC(const Function &Fn, std::string GCName);
104
105 /// Return the GC for a function
106 const std::string &getGC(const Function &Fn);
107
108 /// Remove the GC for a function
109 void deleteGC(const Function &Fn);
110
111 /// Return true if the Context runtime configuration is set to discard all
112 /// value names. When true, only GlobalValue names will be available in the
113 /// IR.
114 bool shouldDiscardValueNames() const;
115
116 /// Set the Context runtime configuration to discard all value name (but
117 /// GlobalValue). Clients can use this flag to save memory and runtime,
118 /// especially in release mode.
119 void setDiscardValueNames(bool Discard);
120
121 /// Whether there is a string map for uniquing debug info
122 /// identifiers across the context. Off by default.
123 bool isODRUniquingDebugTypes() const;
124 void enableDebugTypeODRUniquing();
125 void disableDebugTypeODRUniquing();
126
127 typedef void (*InlineAsmDiagHandlerTy)(const SMDiagnostic&, void *Context,
128 unsigned LocCookie);
129
130 /// Defines the type of a diagnostic handler.
131 /// \see LLVMContext::setDiagnosticHandler.
132 /// \see LLVMContext::diagnose.
133 typedef void (*DiagnosticHandlerTy)(const DiagnosticInfo &DI, void *Context);
134
135 /// Defines the type of a yield callback.
136 /// \see LLVMContext::setYieldCallback.
137 typedef void (*YieldCallbackTy)(LLVMContext *Context, void *OpaqueHandle);
138
139 /// setInlineAsmDiagnosticHandler - This method sets a handler that is invoked
140 /// when problems with inline asm are detected by the backend. The first
141 /// argument is a function pointer and the second is a context pointer that
142 /// gets passed into the DiagHandler.
143 ///
144 /// LLVMContext doesn't take ownership or interpret either of these
145 /// pointers.
146 void setInlineAsmDiagnosticHandler(InlineAsmDiagHandlerTy DiagHandler,
147 void *DiagContext = nullptr);
148
149 /// getInlineAsmDiagnosticHandler - Return the diagnostic handler set by
150 /// setInlineAsmDiagnosticHandler.
151 InlineAsmDiagHandlerTy getInlineAsmDiagnosticHandler() const;
152
153 /// getInlineAsmDiagnosticContext - Return the diagnostic context set by
154 /// setInlineAsmDiagnosticHandler.
155 void *getInlineAsmDiagnosticContext() const;
156
157 /// setDiagnosticHandler - This method sets a handler that is invoked
158 /// when the backend needs to report anything to the user. The first
159 /// argument is a function pointer and the second is a context pointer that
160 /// gets passed into the DiagHandler. The third argument should be set to
161 /// true if the handler only expects enabled diagnostics.
162 ///
163 /// LLVMContext doesn't take ownership or interpret either of these
164 /// pointers.
165 void setDiagnosticHandler(DiagnosticHandlerTy DiagHandler,
166 void *DiagContext = nullptr,
167 bool RespectFilters = false);
168
169 /// getDiagnosticHandler - Return the diagnostic handler set by
170 /// setDiagnosticHandler.
171 DiagnosticHandlerTy getDiagnosticHandler() const;
172
173 /// getDiagnosticContext - Return the diagnostic context set by
174 /// setDiagnosticContext.
175 void *getDiagnosticContext() const;
176
177 /// \brief Get the prefix that should be printed in front of a diagnostic of
178 /// the given \p Severity
179 static const char *getDiagnosticMessagePrefix(DiagnosticSeverity Severity);
180
181 /// \brief Report a message to the currently installed diagnostic handler.
182 ///
183 /// This function returns, in particular in the case of error reporting
184 /// (DI.Severity == \a DS_Error), so the caller should leave the compilation
185 /// process in a self-consistent state, even though the generated code
186 /// need not be correct.
187 ///
188 /// The diagnostic message will be implicitly prefixed with a severity keyword
189 /// according to \p DI.getSeverity(), i.e., "error: " for \a DS_Error,
190 /// "warning: " for \a DS_Warning, and "note: " for \a DS_Note.
191 void diagnose(const DiagnosticInfo &DI);
192
193 /// \brief Registers a yield callback with the given context.
194 ///
195 /// The yield callback function may be called by LLVM to transfer control back
196 /// to the client that invoked the LLVM compilation. This can be used to yield
197 /// control of the thread, or perform periodic work needed by the client.
198 /// There is no guaranteed frequency at which callbacks must occur; in fact,
199 /// the client is not guaranteed to ever receive this callback. It is at the
200 /// sole discretion of LLVM to do so and only if it can guarantee that
201 /// suspending the thread won't block any forward progress in other LLVM
202 /// contexts in the same process.
203 ///
204 /// At a suspend point, the state of the current LLVM context is intentionally
205 /// undefined. No assumptions about it can or should be made. Only LLVM
206 /// context API calls that explicitly state that they can be used during a
207 /// yield callback are allowed to be used. Any other API calls into the
208 /// context are not supported until the yield callback function returns
209 /// control to LLVM. Other LLVM contexts are unaffected by this restriction.
210 void setYieldCallback(YieldCallbackTy Callback, void *OpaqueHandle);
211
212 /// \brief Calls the yield callback (if applicable).
213 ///
214 /// This transfers control of the current thread back to the client, which may
215 /// suspend the current thread. Only call this method when LLVM doesn't hold
216 /// any global mutex or cannot block the execution in another LLVM context.
217 void yield();
218
219 /// emitError - Emit an error message to the currently installed error handler
220 /// with optional location information. This function returns, so code should
221 /// be prepared to drop the erroneous construct on the floor and "not crash".
222 /// The generated code need not be correct. The error message will be
223 /// implicitly prefixed with "error: " and should not end with a ".".
224 void emitError(unsigned LocCookie, const Twine &ErrorStr);
225 void emitError(const Instruction *I, const Twine &ErrorStr);
226 void emitError(const Twine &ErrorStr);
227
228 /// \brief Query for a debug option's value.
229 ///
230 /// This function returns typed data populated from command line parsing.
231 template <typename ValT, typename Base, ValT(Base::*Mem)>
getOption()232 ValT getOption() const {
233 return OptionRegistry::instance().template get<ValT, Base, Mem>();
234 }
235
236 /// \brief Access the object which manages optimization bisection for failure
237 /// analysis.
238 OptBisect &getOptBisect();
239 private:
240 LLVMContext(LLVMContext&) = delete;
241 void operator=(LLVMContext&) = delete;
242
243 /// addModule - Register a module as being instantiated in this context. If
244 /// the context is deleted, the module will be deleted as well.
245 void addModule(Module*);
246
247 /// removeModule - Unregister a module from this context.
248 void removeModule(Module*);
249
250 // Module needs access to the add/removeModule methods.
251 friend class Module;
252 };
253
254 // Create wrappers for C Binding types (see CBindingWrapping.h).
DEFINE_SIMPLE_CONVERSION_FUNCTIONS(LLVMContext,LLVMContextRef)255 DEFINE_SIMPLE_CONVERSION_FUNCTIONS(LLVMContext, LLVMContextRef)
256
257 /* Specialized opaque context conversions.
258 */
259 inline LLVMContext **unwrap(LLVMContextRef* Tys) {
260 return reinterpret_cast<LLVMContext**>(Tys);
261 }
262
wrap(const LLVMContext ** Tys)263 inline LLVMContextRef *wrap(const LLVMContext **Tys) {
264 return reinterpret_cast<LLVMContextRef*>(const_cast<LLVMContext**>(Tys));
265 }
266
267 }
268
269 #endif
270