On Fri, Jan 6, 2017 at 12:16 PM Eric Fiselier via cfe-commits < cfe-commits@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@lists.llvm.org > http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits >
_______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
