[libcxx] r291275 - [libc++] Cleanup and document <__threading_support>
Eric Fiselier via cfe-commits
cfe-commits at lists.llvm.org
Fri Jan 6 15:26:32 PST 2017
Should be fixed in r291298. Sorry for the breakage.
/Eric
On Fri, Jan 6, 2017 at 4:18 PM, Eric Fiselier <eric at efcs.ca> wrote:
> 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/Design
>>> Docs/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/CMakeLi
>>> sts.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/CMakeL
>>> ists.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.si
>>> te.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/suppor
>>> t/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/d74bd160/attachment-0001.html>
More information about the cfe-commits
mailing list