rmaprath created this revision. rmaprath added reviewers: EricWF, mclow.lists. rmaprath added a subscriber: cfe-commits.
Trying to improve the documentation for the external-thread-library configuration of `libc++`. https://reviews.llvm.org/D28610 Files: docs/DesignDocs/ThreadingSupportAPI.rst Index: docs/DesignDocs/ThreadingSupportAPI.rst =================================================================== --- docs/DesignDocs/ThreadingSupportAPI.rst +++ docs/DesignDocs/ThreadingSupportAPI.rst @@ -33,13 +33,22 @@ External Threading Library ========================== -Normally ``<__threading_support>`` provides inline definitions to each internal -threading API function it declares. However libc++ also supports using an -external library to provide the definitions. - -When ``_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL`` libc++ does not provide inline -definitions for the internal API, instead assuming the definitions will be -provided by an external library. +libc++ can be compiled with its internal threading API delegated to an external +library. Such a configuration is useful for library vendors who wish to +distribute a thread-agnostic libc++ library, where the users of the library are +expected to provide the implementation of the libc++ internal threading API. + +On a production setting, this would be achieved through a custom +``<__external_threading>`` header, which declares the libc++ internal threading +API but leaves out the implementation. + +The ``-DLIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY`` option allows building libc++ in +such a configuration while allowing it to be tested on a platform that supports +any of the threading implementations available in ``__threading_support`` +header. Therefore, the main purpose of this option is to allow testing of this +paricular configuration of the library without being tied to a vendor-specific +threading implementation. This option is only meant to be used by libc++ library +developers. Threading Configuration Macros ==============================
Index: docs/DesignDocs/ThreadingSupportAPI.rst =================================================================== --- docs/DesignDocs/ThreadingSupportAPI.rst +++ docs/DesignDocs/ThreadingSupportAPI.rst @@ -33,13 +33,22 @@ External Threading Library ========================== -Normally ``<__threading_support>`` provides inline definitions to each internal -threading API function it declares. However libc++ also supports using an -external library to provide the definitions. - -When ``_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL`` libc++ does not provide inline -definitions for the internal API, instead assuming the definitions will be -provided by an external library. +libc++ can be compiled with its internal threading API delegated to an external +library. Such a configuration is useful for library vendors who wish to +distribute a thread-agnostic libc++ library, where the users of the library are +expected to provide the implementation of the libc++ internal threading API. + +On a production setting, this would be achieved through a custom +``<__external_threading>`` header, which declares the libc++ internal threading +API but leaves out the implementation. + +The ``-DLIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY`` option allows building libc++ in +such a configuration while allowing it to be tested on a platform that supports +any of the threading implementations available in ``__threading_support`` +header. Therefore, the main purpose of this option is to allow testing of this +paricular configuration of the library without being tied to a vendor-specific +threading implementation. This option is only meant to be used by libc++ library +developers. Threading Configuration Macros ==============================
_______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
