Written by Chris Lattner, Dinakar Dhurjati, Gabor Greif, - Joel Stanley and - Reid Spencer
+ Joel Stanley, + Reid Spencer and + Owen Anderson @@ -2129,6 +2138,104 @@ comment for more details. + ++This section describes the interaction of the LLVM APIs with multithreading, +both on the part of client applications, and in the JIT, in the hosted +application. +
+ ++Note that LLVM's support for multithreading is still relatively young. Up +through version 2.5, the execution of threaded hosted applications was +supported, but not threaded client access to the APIs. While this use case is +now supported, clients must adhere to the guidelines specified below to +ensure proper operation in multithreaded mode. +
+ ++Note that, on Unix-like platforms, LLVM requires the presence of GCC's atomic +intrinsics in order to support threaded operation. If you need a +multhreading-capable LLVM on a platform without a suitably modern system +compiler, consider compiling LLVM and LLVM-GCC in single-threaded mode, and +using the resultant compiler to build a copy of LLVM with multithreading +support. +
++In order to properly protect its internal data structures while avoiding +excessive locking overhead in the single-threaded case, the LLVM APIs require +that the client invoke llvm_start_multithreaded(). This call must +complete before any other threads attempt to invoke LLVM APIs. Any +attempts to call LLVM APIs from multiple threads before +llvm_start_multithreaded returns can and will cause corruption of +LLVM's internal data. +
+ ++A caveat: before llvm_start_multithreaded() has been invoked, all +llvm::sys::Mutex acquisitions and releases will become no-ops. This +means that llvm_start_multithreaded() must be invoked before a threaded +application can be executed in the JIT. +
++When you are done using the LLVM APIs, you should call llvm_shutdown() +to deallocate memory used for internal structures. This call must not begin +while any other threads are still issuing LLVM API calls. Doing so is likely +to result in garbage data or crashes. +
+ ++Note that, if you use scope-based shutdown, you can use the +llvm_shutdown_obj class, which calls llvm_shutdown() in its +destructor. +
+ManagedStatic is a utility class in LLVM used to implement static +initialization of static resources, such as the global type tables. Before the +invocation of llvm_shutdown(), it implements a simple lazy +initialization scheme. Once llvm_start_multithreaded() returns, +however, it uses double-checked locking to implement thread-safe lazy +initialization. +
+ ++Note that, because no other threads are allowed to issue LLVM API calls before +llvm_start_multithreaded() returns, it is possible to have +ManagedStatics of llvm::sys::Mutexs. +
+