From 1ad70e3bb4a6cec131613d0db6257ae4812542c3 Mon Sep 17 00:00:00 2001 From: Owen Anderson Date: Tue, 16 Jun 2009 18:04:19 +0000 Subject: [PATCH] Update the threading section to reflect current plans/implementation. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@73521 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/ProgrammersManual.html | 52 +++++++++++++++++++++++++------------ 1 file changed, 36 insertions(+), 16 deletions(-) diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index 0da88bf33a6..368b503d4e9 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -132,7 +132,8 @@ with another Value
  • Threads and LLVM @@ -2172,27 +2173,38 @@ support.
    - Entering Threaded Mode with - llvm_start_multithreaded() + 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 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. +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.

    -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. +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's 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 care must be taken to ensure +that side exits and the like do not accidentally result in concurrent LLVM API +calls.

    @@ -2204,9 +2216,10 @@ 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. +to 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().

    @@ -2235,6 +2248,13 @@ 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.

    + +

    +The llvm_acquire_global_lock() and llvm_release_global_lock +APIs provide access to the global lock used to implement the double-checked +locking for lazy initialization. These should only be used internally to LLVM, +and only if you know what you're doing! +

    -- 2.34.1