using the resultant compiler to build a copy of LLVM with multithreading
support.
+.. _startmultithreaded:
+
+Entering and Exiting Multithreaded Mode
+---------------------------------------
+
+In order to properly protect its internal data structures while avoiding
+excessive locking overhead in the single-threaded case, the LLVM must intialize
+certain data structures necessary to provide guards around its internals. To do
+so, the client program must invoke ``llvm_start_multithreaded()`` before making
+any concurrent LLVM API calls. To subsequently tear down these structures, use
+the ``llvm_stop_multithreaded()`` call. You can also use the
+``llvm_is_multithreaded()`` call to check the status of multithreaded mode.
+
+Note that both of these calls must be made *in isolation*. That is to say that
+no other LLVM API calls may be executing at any time during the execution of
+``llvm_start_multithreaded()`` or ``llvm_stop_multithreaded``. It is the
+client's responsibility to enforce this isolation.
+
+The return value of ``llvm_start_multithreaded()`` indicates the success or
+failure of the initialization. Failure typically indicates that your copy of
+LLVM was built without multithreading support, typically because GCC atomic
+intrinsics were not found in your system compiler. In this case, the LLVM API
+will not be safe for concurrent calls. However, it *will* be safe for hosting
+threaded applications in the JIT, though :ref:`care must be taken
+<jitthreading>` to ensure that side exits and the like do not accidentally
+result in concurrent LLVM API calls.
+
.. _shutdown:
Ending Execution with ``llvm_shutdown()``
-----------------------------------------
When you are done using the LLVM APIs, you should call ``llvm_shutdown()`` to
-deallocate memory used for internal structures.
+deallocate memory used for internal structures. This will also invoke
+``llvm_stop_multithreaded()`` if LLVM is operating in multithreaded mode. As
+such, ``llvm_shutdown()`` requires the same isolation guarantees as
+``llvm_stop_multithreaded()``.
+
+Note that, if you use scope-based shutdown, you can use the
+``llvm_shutdown_obj`` class, which calls ``llvm_shutdown()`` in its destructor.
.. _managedstatic:
------------------------------------------
``ManagedStatic`` is a utility class in LLVM used to implement static
-initialization of static resources, such as the global type tables. In a
-single-threaded environment, it implements a simple lazy initialization scheme.
-When LLVM is compiled with support for multi-threading, however, it uses
+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
+``ManagedStatic``\ s of ``llvm::sys::Mutex``\ s.
+
.. _llvmcontext:
Achieving Isolation with ``LLVMContext``
* @{
*/
-/** Deprecated: Multi-threading can only be enabled/disabled with the compile
- time define LLVM_ENABLE_THREADS. This function always returns
- LLVMIsMultithreaded(). */
+/** Allocate and initialize structures needed to make LLVM safe for
+ multithreading. The return value indicates whether multithreaded
+ initialization succeeded. Must be executed in isolation from all
+ other LLVM api calls.
+ @see llvm::llvm_start_multithreaded */
LLVMBool LLVMStartMultithreaded(void);
-/** Deprecated: Multi-threading can only be enabled/disabled with the compile
- time define LLVM_ENABLE_THREADS. */
+/** Deallocate structures necessary to make LLVM safe for multithreading.
+ Must be executed in isolation from all other LLVM api calls.
+ @see llvm::llvm_stop_multithreaded */
void LLVMStopMultithreaded(void);
/** Check whether LLVM is executing in thread-safe mode or not.
/// llvm_shutdown() when it is destroyed.
struct llvm_shutdown_obj {
llvm_shutdown_obj() { }
+ explicit llvm_shutdown_obj(bool multithreaded) {
+ if (multithreaded) llvm_start_multithreaded();
+ }
~llvm_shutdown_obj() { llvm_shutdown(); }
};
//
//===----------------------------------------------------------------------===//
//
-// This file declares helper functions for running LLVM in a multi-threaded
-// environment.
+// TThis file defines llvm_start_multithreaded() and friends.
//
//===----------------------------------------------------------------------===//
#define LLVM_SUPPORT_THREADING_H
namespace llvm {
- /// Returns true if LLVM is compiled with support for multi-threading, and
- /// false otherwise.
+ /// llvm_start_multithreaded - Allocate and initialize structures needed to
+ /// make LLVM safe for multithreading. The return value indicates whether
+ /// multithreaded initialization succeeded. LLVM will still be operational
+ /// on "failed" return, and will still be safe for hosting threading
+ /// applications in the JIT, but will not be safe for concurrent calls to the
+ /// LLVM APIs.
+ /// THIS MUST EXECUTE IN ISOLATION FROM ALL OTHER LLVM API CALLS.
+ bool llvm_start_multithreaded();
+
+ /// llvm_stop_multithreaded - Deallocate structures necessary to make LLVM
+ /// safe for multithreading.
+ /// THIS MUST EXECUTE IN ISOLATION FROM ALL OTHER LLVM API CALLS.
+ void llvm_stop_multithreaded();
+
+ /// llvm_is_multithreaded - Check whether LLVM is executing in thread-safe
+ /// mode or not.
bool llvm_is_multithreaded();
/// llvm_execute_on_thread - Execute the given \p UserFn on a separate
/*===-- Threading ------------------------------------------------------===*/
LLVMBool LLVMStartMultithreaded() {
- return LLVMIsMultithreaded();
+ return llvm_start_multithreaded();
}
void LLVMStopMultithreaded() {
+ llvm_stop_multithreaded();
}
LLVMBool LLVMIsMultithreaded() {
//
//===----------------------------------------------------------------------===//
//
-// This file defines helper functions for running LLVM in a multi-threaded
-// environment.
+// This file implements llvm_start_multithreaded() and friends.
//
//===----------------------------------------------------------------------===//
using namespace llvm;
-bool llvm::llvm_is_multithreaded() {
+static bool multithreaded_mode = false;
+
+bool llvm::llvm_start_multithreaded() {
#if LLVM_ENABLE_THREADS != 0
+ assert(!multithreaded_mode && "Already multithreaded!");
+ multithreaded_mode = true;
+
+ // We fence here to ensure that all initialization is complete BEFORE we
+ // return from llvm_start_multithreaded().
+ sys::MemoryFence();
return true;
#else
return false;
#endif
}
+void llvm::llvm_stop_multithreaded() {
+#if LLVM_ENABLE_THREADS != 0
+ assert(multithreaded_mode && "Not currently multithreaded!");
+
+ // We fence here to insure that all threaded operations are complete BEFORE we
+ // return from llvm_stop_multithreaded().
+ sys::MemoryFence();
+
+ multithreaded_mode = false;
+#endif
+}
+
+bool llvm::llvm_is_multithreaded() {
+ return multithreaded_mode;
+}
+
#if LLVM_ENABLE_THREADS != 0 && defined(HAVE_PTHREAD_H)
#include <pthread.h>
void *p1 = test1::allocate_stack(a1);
void *p2 = test1::allocate_stack(a2);
+ llvm_start_multithreaded();
pthread_t t1, t2;
pthread_create(&t1, &a1, test1::helper, nullptr);
pthread_create(&t2, &a2, test1::helper, nullptr);
pthread_join(t2, nullptr);
free(p1);
free(p2);
+ llvm_stop_multithreaded();
}
#endif
projects / oota-llvm.git / commitdiff