diff options
Diffstat (limited to 'llvm/docs')
| -rw-r--r-- | llvm/docs/ORCv2.rst | 66 |
1 files changed, 38 insertions, 28 deletions
diff --git a/llvm/docs/ORCv2.rst b/llvm/docs/ORCv2.rst index 4f9e08b9a15..d39fcd17407 100644 --- a/llvm/docs/ORCv2.rst +++ b/llvm/docs/ORCv2.rst @@ -153,7 +153,7 @@ Design Overview ORC's JIT'd program model aims to emulate the linking and symbol resolution rules used by the static and dynamic linkers. This allows ORC to JIT arbitrary LLVM IR, including IR produced by an ordinary static compiler (e.g. -clang) that uses constructs like symbol linkage and visibility, and weak [4]_ +clang) that uses constructs like symbol linkage and visibility, and weak [3]_ and common symbol definitions. To see how this works, imagine a program ``foo`` which links against a pair @@ -441,7 +441,7 @@ ThreadSafeModule and ThreadSafeContext are wrappers around Modules and LLVMContexts respectively. A ThreadSafeModule is a pair of a std::unique_ptr<Module> and a (possibly shared) ThreadSafeContext value. A ThreadSafeContext is a pair of a std::unique_ptr<LLVMContext> and a lock. -This design serves two purposes: providing both a locking scheme and lifetime +This design serves two purposes: providing a locking scheme and lifetime management for LLVMContexts. The ThreadSafeContext may be locked to prevent accidental concurrent access by two Modules that use the same LLVMContext. The underlying LLVMContext is freed once all ThreadSafeContext values pointing @@ -471,33 +471,49 @@ Before using a ThreadSafeContext, clients should ensure that either the context is only accessible on the current thread, or that the context is locked. In the example above (where the context is never locked) we rely on the fact that both ``TSM1`` and ``TSM2``, and TSCtx are all created on one thread. If a context is -going to be shared between threads then it must be locked before the context, -or any Modules attached to it, are accessed. When code is added to in-tree IR -layers this locking is is done automatically by the -``BasicIRLayerMaterializationUnit::materialize`` method. In all other -situations, for example when writing a custom IR materialization unit, or -constructing a new ThreadSafeModule from higher-level program representations, -locking must be done explicitly: +going to be shared between threads then it must be locked before any accessing +or creating any Modules attached to it. E.g. .. code-block:: c++ - void HighLevelRepresentationLayer::emit(MaterializationResponsibility R, - HighLevelProgramRepresentation H) { - // Get or create a context value that may be shared between threads. - ThreadSafeContext TSCtx = getContext(); - // Lock the context to prevent concurrent access. - auto Lock = TSCtx.getLock(); + ThreadSafeContext TSCtx(llvm::make_unique<LLVMContext>()); - // IRGen a module onto the locked Context. - ThreadSafeModule TSM(IRGen(H, *TSCtx.getContext()), TSCtx); + ThreadPool TP(NumThreads); + JITStack J; - // Emit the module to the base layer with the context still locked. - BaseIRLayer.emit(std::move(R), std::move(TSM)); - } + for (auto &ModulePath : ModulePaths) { + TP.async( + [&]() { + auto Lock = TSCtx.getLock(); + + auto M = loadModuleOnContext(ModulePath, TSCtx.getContext()); + + J.addModule(ThreadSafeModule(std::move(M), TSCtx)); + }); + } + + TP.wait(); + +To make exclusive access to Modules easier to manage the ThreadSafeModule class +provides a convenince function, ``withModuleDo``, that implicitly (1) locks the +associated context, (2) runs a given function object, (3) unlocks the context, +and (3) returns the result generated by the function object. E.g. + + .. code-block:: c++ + + ThreadSafeModule TSM = getModule(...); + + // Dump the module: + size_t NumFunctionsInModule = + TSM.withModuleDo( + [](Module &M) { // <- Context locked before entering lambda. + return M.size(); + } // <- Context unlocked after leaving. + ); Clients wishing to maximize possibilities for concurrent compilation will want -to create every new ThreadSafeModule on a new ThreadSafeContext [3]_. For this +to create every new ThreadSafeModule on a new ThreadSafeContext. For this reason a convenience constructor for ThreadSafeModule is provided that implicitly constructs a new ThreadSafeContext value from a std::unique_ptr<LLVMContext>: @@ -620,13 +636,7 @@ TBD: Speculative compilation. Object Caches. across processes, however this functionality appears not to have been used. -.. [3] Sharing ThreadSafeModules in a concurrent compilation can be dangerous: - if interdependent modules are loaded on the same context, but compiled - on different threads a deadlock may occur, with each compile waiting for - the other to complete, and the other unable to proceed because the - context is locked. - -.. [4] Weak definitions are currently handled correctly within dylibs, but if +.. [3] Weak definitions are currently handled correctly within dylibs, but if multiple dylibs provide a weak definition of a symbol then each will end up with its own definition (similar to how weak definitions are handled in Windows DLLs). This will be fixed in the future. |
