[llvm] r211070 - Programmer's Manual changes.

[Zachary Turner]

This change was reverted in r211072 due to accidentally pushing a whole
branch instead of a single CL.


On Mon, Jun 16, 2014 at 3:40 PM, Zachary Turner <zturner at google.com> wrote:

> Author: zturner
> Date: Mon Jun 16 17:40:48 2014
> New Revision: 211070
>
> URL: http://llvm.org/viewvc/llvm-project?rev=211070&view=rev
> Log:
> Programmer's Manual changes.
>
> Modified:
>     llvm/trunk/docs/ProgrammersManual.rst
>
> Modified: llvm/trunk/docs/ProgrammersManual.rst
> URL:
> http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/ProgrammersManual.rst?rev=211070&r1=211069&r2=211070&view=diff
>
> ==============================================================================
> --- llvm/trunk/docs/ProgrammersManual.rst (original)
> +++ llvm/trunk/docs/ProgrammersManual.rst Mon Jun 16 17:40:48 2014
> @@ -2170,67 +2170,24 @@ compiler, consider compiling LLVM and LL
>  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.  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.
> -
> +deallocate memory used for internal structures.
>  .. _managedstatic:
>
>  Lazy Initialization with ``ManagedStatic``
>  ------------------------------------------
>
>  ``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
> +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
>  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.
> -
> -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!
> -
>  .. _llvmcontext:
>
>  Achieving Isolation with ``LLVMContext``
>
>
> _______________________________________________
> llvm-commits mailing list
> llvm-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140617/4101709f/attachment.html>