[libcxx] r291275 - [libc++] Cleanup and document <__threading_support>
Eric Fiselier via cfe-commits
cfe-commits at lists.llvm.org
Fri Jan 6 15:18:24 PST 2017
Hi David,
Thanks for the information. Looking into it now.
/Eric
On Fri, Jan 6, 2017 at 4:02 PM, David Blaikie <dblaikie at gmail.com> wrote:
>
>
> On Fri, Jan 6, 2017 at 12:16 PM Eric Fiselier via cfe-commits <
> cfe-commits at lists.llvm.org> wrote:
>
>> Author: ericwf
>> Date: Fri Jan 6 14:05:40 2017
>> New Revision: 291275
>>
>> URL: http://llvm.org/viewvc/llvm-project?rev=291275&view=rev
>> Log:
>> [libc++] Cleanup and document <__threading_support>
>>
>> Summary:
>> This patch attempts to clean up the macro configuration mess in
>> `<__threading_support>`, specifically the mess involving external threading
>> variants. Additionally this patch adds design documentation for
>> `<__threading_support>` and the configuration macros it uses.
>>
>> The primary change in this patch is separating the idea of an "external
>> API" provided by `<__external_threading>` and the idea of having an
>> external threading library. Now `_LIBCPP_HAS_THREAD_API_EXTERNAL` means
>> that libc++ should use `<__external_threading>` and that the header is
>> expected to exist. Additionally the new macro `_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL`
>> is now used to configure for using an "external library" with the default
>> threading API.
>>
>> Reviewers: compnerd, rmaprath
>>
>> Subscribers: smeenai, cfe-commits, mgorny
>>
>> Differential Revision: https://reviews.llvm.org/D28316
>>
>> Added:
>> libcxx/trunk/docs/DesignDocs/ThreadingSupportAPI.rst
>> Modified:
>> libcxx/trunk/CMakeLists.txt
>> libcxx/trunk/docs/index.rst
>> libcxx/trunk/include/__config
>> libcxx/trunk/include/__config_site.in
>> libcxx/trunk/include/__threading_support
>> libcxx/trunk/lib/CMakeLists.txt
>> libcxx/trunk/test/CMakeLists.txt
>> libcxx/trunk/test/lit.site.cfg.in
>> libcxx/trunk/test/support/external_threads.cpp
>>
>> Modified: libcxx/trunk/CMakeLists.txt
>> URL: http://llvm.org/viewvc/llvm-project/libcxx/trunk/
>> CMakeLists.txt?rev=291275&r1=291274&r2=291275&view=diff
>> ============================================================
>> ==================
>> --- libcxx/trunk/CMakeLists.txt (original)
>> +++ libcxx/trunk/CMakeLists.txt Fri Jan 6 14:05:40 2017
>> @@ -169,6 +169,9 @@ option(LIBCXX_HAS_PTHREAD_API "Ignore au
>> option(LIBCXX_HAS_EXTERNAL_THREAD_API
>> "Build libc++ with an externalized threading API.
>> This option may only be set to ON when LIBCXX_ENABLE_THREADS=ON." OFF)
>> +option(LIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY
>> + "Build libc++ with an externalized threading library.
>> + This option may only be set to ON when LIBCXX_ENABLE_THREADS=ON"
>> OFF)
>>
>> # Misc options ------------------------------
>> ----------------------------------
>> # FIXME: Turn -pedantic back ON. It is currently off because it warns
>> @@ -230,6 +233,17 @@ if(NOT LIBCXX_ENABLE_THREADS)
>> message(FATAL_ERROR "LIBCXX_HAS_EXTERNAL_THREAD_API can only be set
>> to ON"
>> " when LIBCXX_ENABLE_THREADS is also set to ON.")
>> endif()
>> + if (LIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY)
>> + message(FATAL_ERROR "LIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY can only
>> be set "
>> + "to ON when LIBCXX_ENABLE_THREADS is also set to
>> ON.")
>> + endif()
>> +
>> +endif()
>> +
>> +if (LIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY AND LIBCXX_HAS_EXTERNAL_THREAD_
>> API)
>> + message(FATAL_ERROR "The options LIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY
>> and "
>> + "LIBCXX_HAS_EXTERNAL_THREAD_API cannot both be ON
>> at "
>> + "the same time")
>> endif()
>>
>> if(LIBCXX_HAS_PTHREAD_API AND LIBCXX_HAS_EXTERNAL_THREAD_API)
>> @@ -520,6 +534,7 @@ config_define_if_not(LIBCXX_ENABLE_THREA
>>
>> config_define_if(LIBCXX_HAS_PTHREAD_API _LIBCPP_HAS_THREAD_API_PTHREAD)
>> config_define_if(LIBCXX_HAS_EXTERNAL_THREAD_API _LIBCPP_HAS_THREAD_API_
>> EXTERNAL)
>> +config_define_if(LIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY
>> _LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL)
>> config_define_if(LIBCXX_HAS_MUSL_LIBC _LIBCPP_HAS_MUSL_LIBC)
>>
>> # By default libc++ on Windows expects to use a shared library, which
>> requires
>>
>> Added: libcxx/trunk/docs/DesignDocs/ThreadingSupportAPI.rst
>> URL: http://llvm.org/viewvc/llvm-project/libcxx/trunk/docs/DesignDocs/
>> ThreadingSupportAPI.rst?rev=291275&view=auto
>> ============================================================
>> ==================
>> --- libcxx/trunk/docs/DesignDocs/ThreadingSupportAPI.rst (added)
>> +++ libcxx/trunk/docs/DesignDocs/ThreadingSupportAPI.rst Fri Jan 6
>> 14:05:40 2017
>> @@ -0,0 +1,70 @@
>> +=====================
>> +Threading Support API
>> +=====================
>> +
>> +.. contents::
>> + :local:
>> +
>> +Overview
>> +========
>> +
>> +Libc++ supports using multiple different threading models and
>> configurations
>> +to implement the threading parts of libc++, including ``<thread>`` and
>> ``<mutex>``.
>> +These different models provide entirely different interfaces from each
>> +other. To address this libc++ wraps the underlying threading API in a
>> new and
>> +consistent API, which it uses internally to implement threading
>> primitives.
>> +
>> +The ``<__threading_support>`` header is where libc++ defines its internal
>> +threading interface. It contains forward declarations of the internal
>> threading
>> +interface as well as definitions for the interface.
>> +
>> +External Threading API and the ``<__external_threading>`` header
>> +================================================================
>> +
>> +In order to support vendors with custom threading API's libc++ allows the
>> +entire internal threading interface to be provided by an external,
>> +vendor provided, header.
>> +
>> +When ``_LIBCPP_HAS_THREAD_API_EXTERNAL`` is defined the
>> ``<__threading_support>``
>> +header simply forwards to the ``<__external_threading>`` header (which
>> must exist).
>> +It is expected that the ``<__external_threading>`` header provide the
>> exact
>> +interface normally provided by ``<__threading_support>``.
>> +
>> +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.
>> +
>> +Threading Configuration Macros
>> +==============================
>> +
>> +**_LIBCPP_HAS_NO_THREADS**
>> + This macro is defined when libc++ is built without threading support.
>> It
>> + should not be manually defined by the user.
>> +
>> +**_LIBCPP_HAS_THREAD_API_EXTERNAL**
>> + This macro is defined when libc++ should use the
>> ``<__external_threading>``
>> + header to provide the internal threading API. This macro overrides
>> + ``_LIBCPP_HAS_THREAD_API_PTHREAD``.
>> +
>> +**_LIBCPP_HAS_THREAD_API_PTHREAD**
>> + This macro is defined when libc++ should use POSIX threads to
>> implement the
>> + internal threading API.
>> +
>> +**_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL**
>> + This macro is defined when libc++ expects the definitions of the
>> internal
>> + threading API to be provided by an external library. When defined
>> + ``<__threading_support>`` will only provide the forward declarations
>> and
>> + typedefs for the internal threading API.
>> +
>> +**_LIBCPP_BUILDING_THREAD_LIBRARY_EXTERNAL**
>> + This macro is used to build an external threading library using the
>> + ``<__threading_support>``. Specifically it exposes the threading API
>> + definitions in ``<__threading_support>`` as non-inline definitions
>> meant to
>> + be compiled into a library.
>>
>> Modified: libcxx/trunk/docs/index.rst
>> URL: http://llvm.org/viewvc/llvm-project/libcxx/trunk/docs/
>> index.rst?rev=291275&r1=291274&r2=291275&view=diff
>> ============================================================
>> ==================
>> --- libcxx/trunk/docs/index.rst (original)
>> +++ libcxx/trunk/docs/index.rst Fri Jan 6 14:05:40 2017
>> @@ -131,7 +131,7 @@ Design Documents
>> DesignDocs/CapturingConfigInfo
>> DesignDocs/ABIVersioning
>> DesignDocs/VisibilityMacros
>> -
>> + DesignDocs/ThreadingSupportAPI
>>
>> * `<atomic> design <http://libcxx.llvm.org/atomic_design.html>`_
>> * `<type_traits> design <http://libcxx.llvm.org/type_traits_design.html
>> >`_
>>
>> Modified: libcxx/trunk/include/__config
>> URL: http://llvm.org/viewvc/llvm-project/libcxx/trunk/include/_
>> _config?rev=291275&r1=291274&r2=291275&view=diff
>> ============================================================
>> ==================
>> --- libcxx/trunk/include/__config (original)
>> +++ libcxx/trunk/include/__config Fri Jan 6 14:05:40 2017
>> @@ -891,9 +891,7 @@ _LIBCPP_FUNC_VIS extern "C" void __sanit
>> #endif
>>
>> // Thread API
>> -#if !defined(_LIBCPP_HAS_NO_THREADS) && \
>> - !defined(_LIBCPP_HAS_THREAD_API_PTHREAD) && \
>> - !defined(_LIBCPP_HAS_THREAD_API_EXTERNAL)
>>
>
> This change looks like it breaks existing functionality where if a user
> defines _LIBCPP_HAS_THREAD_API_PTHREAD they don't need to have any of the
> detected __FOO__ OS markers below.
>
> (with this change, even if you say you have pthreads, you still get "No
> thread API" if you're not on one of those listed OSs)
>
>
>> +#if !defined(_LIBCPP_HAS_NO_THREADS)
>> # if defined(__FreeBSD__) || \
>> defined(__Fuchsia__) || \
>> defined(__NetBSD__) || \
>> @@ -901,7 +899,9 @@ _LIBCPP_FUNC_VIS extern "C" void __sanit
>> defined(__APPLE__) || \
>> defined(__CloudABI__) || \
>> defined(__sun__)
>> -# define _LIBCPP_HAS_THREAD_API_PTHREAD
>> +# ifndef _LIBCPP_HAS_THREAD_API_PTHREAD
>> +# define _LIBCPP_HAS_THREAD_API_PTHREAD
>> +# endif
>> # else
>> # error "No thread API"
>> # endif // _LIBCPP_HAS_THREAD_API
>>
>> Modified: libcxx/trunk/include/__config_site.in
>> URL: http://llvm.org/viewvc/llvm-project/libcxx/trunk/include/_
>> _config_site.in?rev=291275&r1=291274&r2=291275&view=diff
>> ============================================================
>> ==================
>> --- libcxx/trunk/include/__config_site.in (original)
>> +++ libcxx/trunk/include/__config_site.in Fri Jan 6 14:05:40 2017
>> @@ -21,6 +21,7 @@
>> #cmakedefine _LIBCPP_HAS_MUSL_LIBC
>> #cmakedefine _LIBCPP_HAS_THREAD_API_PTHREAD
>> #cmakedefine _LIBCPP_HAS_THREAD_API_EXTERNAL
>> +#cmakedefine _LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL
>> #cmakedefine _LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS
>>
>> #endif // _LIBCPP_CONFIG_SITE
>>
>> Modified: libcxx/trunk/include/__threading_support
>> URL: http://llvm.org/viewvc/llvm-project/libcxx/trunk/include/_
>> _threading_support?rev=291275&r1=291274&r2=291275&view=diff
>> ============================================================
>> ==================
>> --- libcxx/trunk/include/__threading_support (original)
>> +++ libcxx/trunk/include/__threading_support Fri Jan 6 14:05:40 2017
>> @@ -17,39 +17,17 @@
>> #pragma GCC system_header
>> #endif
>>
>> -#ifndef _LIBCPP_HAS_NO_THREADS
>> -
>> -#ifndef __libcpp_has_include
>> - #ifndef __has_include
>> - #define __libcpp_has_include(x) 0
>> - #else
>> - #define __libcpp_has_include(x) __has_include(x)
>> - #endif
>> -#endif
>> -
>> -#if defined(_LIBCPP_HAS_THREAD_API_EXTERNAL) && \
>> - !__libcpp_has_include(<__external_threading>)
>> -// If the <__external_threading> header is absent, build libc++ against a
>> -// pthread-oriented thread api but leave out its implementation. This
>> setup
>> -// allows building+testing of an externally-threaded library variant (on
>> any
>> -// platform that supports pthreads). Here, an 'externally-threaded'
>> library
>> -// variant is one where the implementation of the libc++ thread api is
>> provided
>> -// as a separate library.
>> -#define _LIBCPP_HAS_THREAD_API_EXTERNAL_PTHREAD
>> -#endif
>> -
>> -#if defined(_LIBCPP_HAS_THREAD_API_EXTERNAL) && \
>> - __libcpp_has_include(<__external_threading>)
>> -#include <__external_threading>
>> -#else
>> +#if defined(_LIBCPP_HAS_THREAD_API_EXTERNAL)
>> +# include <__external_threading>
>> +#elif !defined(_LIBCPP_HAS_NO_THREADS)
>>
>> -#if defined(_LIBCPP_HAS_THREAD_API_PTHREAD) || \
>> - defined(_LIBCPP_HAS_THREAD_API_EXTERNAL_PTHREAD)
>> -#include <pthread.h>
>> -#include <sched.h>
>> +#if defined(_LIBCPP_HAS_THREAD_API_PTHREAD)
>> +# include <pthread.h>
>> +# include <sched.h>
>> #endif
>>
>> -#if defined(_LIBCPP_HAS_THREAD_API_EXTERNAL)
>> +#if defined(_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL) || \
>> + defined(_LIBCPP_BUILDING_THREAD_LIBRARY_EXTERNAL)
>> #define _LIBCPP_THREAD_ABI_VISIBILITY _LIBCPP_FUNC_VIS
>> #else
>> #define _LIBCPP_THREAD_ABI_VISIBILITY inline _LIBCPP_INLINE_VISIBILITY
>> @@ -57,8 +35,7 @@
>>
>> _LIBCPP_BEGIN_NAMESPACE_STD
>>
>> -#if defined(_LIBCPP_HAS_THREAD_API_PTHREAD) || \
>> - defined(_LIBCPP_HAS_THREAD_API_EXTERNAL_PTHREAD)
>> +#if defined(_LIBCPP_HAS_THREAD_API_PTHREAD)
>> // Mutex
>> typedef pthread_mutex_t __libcpp_mutex_t;
>> #define _LIBCPP_MUTEX_INITIALIZER PTHREAD_MUTEX_INITIALIZER
>> @@ -175,8 +152,10 @@ void *__libcpp_tls_get(__libcpp_tls_key
>> _LIBCPP_THREAD_ABI_VISIBILITY
>> int __libcpp_tls_set(__libcpp_tls_key __key, void *__p);
>>
>> -#if defined(_LIBCPP_HAS_THREAD_API_PTHREAD) || \
>> - defined(_LIBCPP_BUILDING_THREAD_API_EXTERNAL_PTHREAD)
>> +#if !defined(_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL) || \
>> + defined(_LIBCPP_BUILDING_THREAD_LIBRARY_EXTERNAL)
>> +
>> +#if defined(_LIBCPP_HAS_THREAD_API_PTHREAD)
>>
>> int __libcpp_recursive_mutex_init(__libcpp_recursive_mutex_t *__m)
>> {
>> @@ -344,10 +323,10 @@ int __libcpp_tls_set(__libcpp_tls_key __
>>
>> #endif // _LIBCPP_HAS_THREAD_API_PTHREAD
>>
>> -_LIBCPP_END_NAMESPACE_STD
>> +#endif // !_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL ||
>> _LIBCPP_BUILDING_THREAD_LIBRARY_EXTERNAL
>>
>> -#endif // !_LIBCPP_HAS_THREAD_API_EXTERNAL || !__libcpp_has_include(<__
>> external_threading>)
>> +_LIBCPP_END_NAMESPACE_STD
>>
>> -#endif // _LIBCPP_HAS_NO_THREADS
>> +#endif // !_LIBCPP_HAS_NO_THREADS
>>
>> #endif // _LIBCPP_THREADING_SUPPORT
>>
>> Modified: libcxx/trunk/lib/CMakeLists.txt
>> URL: http://llvm.org/viewvc/llvm-project/libcxx/trunk/lib/
>> CMakeLists.txt?rev=291275&r1=291274&r2=291275&view=diff
>> ============================================================
>> ==================
>> --- libcxx/trunk/lib/CMakeLists.txt (original)
>> +++ libcxx/trunk/lib/CMakeLists.txt Fri Jan 6 14:05:40 2017
>> @@ -275,7 +275,7 @@ if (LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY)
>> )
>> endif()
>>
>> -if (LIBCXX_HAS_EXTERNAL_THREAD_API)
>> +if (LIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY)
>> file(GLOB LIBCXX_EXTERNAL_THREADING_SUPPORT_SOURCES
>> ../test/support/external_threads.cpp)
>>
>> if (LIBCXX_ENABLE_SHARED)
>>
>> Modified: libcxx/trunk/test/CMakeLists.txt
>> URL: http://llvm.org/viewvc/llvm-project/libcxx/trunk/test/
>> CMakeLists.txt?rev=291275&r1=291274&r2=291275&view=diff
>> ============================================================
>> ==================
>> --- libcxx/trunk/test/CMakeLists.txt (original)
>> +++ libcxx/trunk/test/CMakeLists.txt Fri Jan 6 14:05:40 2017
>> @@ -34,7 +34,7 @@ pythonize_bool(LIBCXXABI_ENABLE_SHARED)
>> pythonize_bool(LIBCXXABI_USE_LLVM_UNWINDER)
>> pythonize_bool(LIBCXX_HAS_ATOMIC_LIB)
>> pythonize_bool(LIBCXX_HAVE_CXX_ATOMICS_WITH_LIB)
>> -pythonize_bool(LIBCXX_HAS_EXTERNAL_THREAD_API)
>> +pythonize_bool(LIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY)
>>
>> # By default, for non-standalone builds, libcxx and libcxxabi share a
>> library
>> # directory.
>>
>> Modified: libcxx/trunk/test/lit.site.cfg.in
>> URL: http://llvm.org/viewvc/llvm-project/libcxx/trunk/test/lit.
>> site.cfg.in?rev=291275&r1=291274&r2=291275&view=diff
>> ============================================================
>> ==================
>> --- libcxx/trunk/test/lit.site.cfg.in (original)
>> +++ libcxx/trunk/test/lit.site.cfg.in Fri Jan 6 14:05:40 2017
>> @@ -28,7 +28,7 @@ config.has_libatomic = "@LIBC
>> config.use_libatomic = "@LIBCXX_HAVE_CXX_ATOMICS_WITH_LIB@"
>>
>> config.libcxxabi_shared = "@LIBCXXABI_ENABLE_SHARED@"
>> -config.cxx_ext_threads = "@LIBCXX_HAS_EXTERNAL_THREAD_API@"
>> +config.cxx_ext_threads = "@LIBCXX_BUILD_EXTERNAL_
>> THREAD_LIBRARY@"
>>
>> # Let the main config do the real work.
>> config.loaded_site_config = True
>>
>> Modified: libcxx/trunk/test/support/external_threads.cpp
>> URL: http://llvm.org/viewvc/llvm-project/libcxx/trunk/test/
>> support/external_threads.cpp?rev=291275&r1=291274&r2=291275&view=diff
>> ============================================================
>> ==================
>> --- libcxx/trunk/test/support/external_threads.cpp (original)
>> +++ libcxx/trunk/test/support/external_threads.cpp Fri Jan 6 14:05:40
>> 2017
>> @@ -6,5 +6,5 @@
>> // Source Licenses. See LICENSE.TXT for details.
>> //
>> //===------------------------------------------------------
>> ----------------===//
>> -#define _LIBCPP_BUILDING_THREAD_API_EXTERNAL_PTHREAD
>> +#define _LIBCPP_BUILDING_THREAD_LIBRARY_EXTERNAL
>> #include <__threading_support>
>>
>>
>> _______________________________________________
>> cfe-commits mailing list
>> cfe-commits at lists.llvm.org
>> http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20170106/683460d8/attachment-0001.html>
More information about the cfe-commits
mailing list