diff options
Diffstat (limited to 'lib/libcxx/docs/DesignDocs')
| -rw-r--r-- | lib/libcxx/docs/DesignDocs/ABIVersioning.rst | 17 | ||||
| -rw-r--r-- | lib/libcxx/docs/DesignDocs/AvailabilityMarkup.rst | 99 | ||||
| -rw-r--r-- | lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst | 88 | ||||
| -rw-r--r-- | lib/libcxx/docs/DesignDocs/DebugMode.rst | 100 | ||||
| -rw-r--r-- | lib/libcxx/docs/DesignDocs/FeatureTestMacros.rst | 44 | ||||
| -rw-r--r-- | lib/libcxx/docs/DesignDocs/FileTimeType.rst | 494 | ||||
| -rw-r--r-- | lib/libcxx/docs/DesignDocs/ThreadingSupportAPI.rst | 83 | ||||
| -rw-r--r-- | lib/libcxx/docs/DesignDocs/VisibilityMacros.rst | 218 |
8 files changed, 0 insertions, 1143 deletions
diff --git a/lib/libcxx/docs/DesignDocs/ABIVersioning.rst b/lib/libcxx/docs/DesignDocs/ABIVersioning.rst deleted file mode 100644 index 5960dd18610..00000000000 --- a/lib/libcxx/docs/DesignDocs/ABIVersioning.rst +++ /dev/null @@ -1,17 +0,0 @@ - -==================== -Libc++ ABI stability -==================== - -Libc++ aims to preserve stable ABI to avoid subtle bugs when code built to the old ABI -is linked with the code build to the new ABI. At the same time, libc++ allows ABI-breaking -improvements and bugfixes for the scenarios when ABI change is not a issue. - -To support both cases, libc++ allows specifying the ABI version at the -build time. The version is defined with a cmake option -LIBCXX_ABI_VERSION. Another option LIBCXX_ABI_UNSTABLE can be used to -include all present ABI breaking features. These options translate -into C++ macro definitions _LIBCPP_ABI_VERSION, _LIBCPP_ABI_UNSTABLE. - -Any ABI-changing feature is placed under it's own macro, _LIBCPP_ABI_XXX, which is enabled -based on the value of _LIBCPP_ABI_VERSION. _LIBCPP_ABI_UNSTABLE, if set, enables all features at once. diff --git a/lib/libcxx/docs/DesignDocs/AvailabilityMarkup.rst b/lib/libcxx/docs/DesignDocs/AvailabilityMarkup.rst deleted file mode 100644 index 4e6d80b50bf..00000000000 --- a/lib/libcxx/docs/DesignDocs/AvailabilityMarkup.rst +++ /dev/null @@ -1,99 +0,0 @@ -=================== -Availability Markup -=================== - -.. contents:: - :local: - -Overview -======== - -Libc++ is used as a system library on macOS and iOS (amongst others). In order -for users to be able to compile a binary that is intended to be deployed to an -older version of the platform, clang provides the -`availability attribute <https://clang.llvm.org/docs/AttributeReference.html#availability>`_ -that can be placed on declarations to describe the lifecycle of a symbol in the -library. - -Design -====== - -When a new feature is introduced that requires dylib support, a macro should be -created in include/__config to mark this feature as unavailable for all the -systems. For example:: - - // Define availability macros. - #if defined(_LIBCPP_USE_AVAILABILITY_APPLE) - # define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable)) - #else if defined(_LIBCPP_USE_AVAILABILITY_SOME_OTHER_VENDOR) - # define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable)) - #else - # define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS - #endif - -When the library is updated by the platform vendor, the markup can be updated. -For example:: - - #define _LIBCPP_AVAILABILITY_SHARED_MUTEX \ - __attribute__((availability(macosx,strict,introduced=10.12))) \ - __attribute__((availability(ios,strict,introduced=10.0))) \ - __attribute__((availability(tvos,strict,introduced=10.0))) \ - __attribute__((availability(watchos,strict,introduced=3.0))) - -In the source code, the macro can be added on a class if the full class requires -type info from the library for example:: - - _LIBCPP_BEGIN_NAMESPACE_EXPERIMENTAL - class _LIBCPP_EXCEPTION_ABI _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS bad_optional_access - : public std::logic_error { - -or on a particular symbol: - - _LIBCPP_OVERRIDABLE_FUNC_VIS _LIBCPP_AVAILABILITY_SIZED_NEW_DELETE void operator delete(void* __p, std::size_t __sz) _NOEXCEPT; - - -Testing -======= - -Some parameters can be passed to lit to run the test-suite and exercise the -availability. - -* The `platform` parameter controls the deployment target. For example lit can - be invoked with `--param=platform=macosx10.8`. Default is the current host. -* The `use_system_cxx_lib` parameter indicates to use another library than the - just built one. Invoking lit with `--param=use_system_cxx_lib=true` will run - the test-suite against the host system library. Alternatively a path to the - directory containing a specific prebuilt libc++ can be used, for example: - `--param=use_system_cxx_lib=/path/to/macOS/10.8/`. - -Tests can be marked as XFAIL based on multiple features made available by lit: - - -* if `--param=platform=macosx10.8` is passed, the following features will be available: - - - availability - - availability=x86_64 - - availability=macosx - - availability=x86_64-macosx - - availability=x86_64-apple-macosx10.8 - - availability=macosx10.8 - - This feature is used to XFAIL a test that *is* using a class or a method marked - as unavailable *and* that is expected to *fail* if deployed on an older system. - -* if `use_system_cxx_lib` and `--param=platform=macosx10.8` are passed to lit, - the following features will also be available: - - - with_system_cxx_lib - - with_system_cxx_lib=x86_64 - - with_system_cxx_lib=macosx - - with_system_cxx_lib=x86_64-macosx - - with_system_cxx_lib=x86_64-apple-macosx10.8 - - with_system_cxx_lib=macosx10.8 - - This feature is used to XFAIL a test that is *not* using a class or a method - marked as unavailable *but* that is expected to fail if deployed on an older - system. For example, if the test exhibits a bug in the libc on a particular - system version, or if the test uses a symbol that is not available on an - older version of the dylib (but for which there is no availability markup, - otherwise the XFAIL should use `availability` above). diff --git a/lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst b/lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst deleted file mode 100644 index 29156bff8bc..00000000000 --- a/lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst +++ /dev/null @@ -1,88 +0,0 @@ -======================================================= -Capturing configuration information during installation -======================================================= - -.. contents:: - :local: - -The Problem -=========== - -Currently the libc++ supports building the library with a number of different -configuration options. Unfortunately all of that configuration information is -lost when libc++ is installed. In order to support "persistent" -configurations libc++ needs a mechanism to capture the configuration options -in the INSTALLED headers. - - -Design Goals -============ - -* The solution should not INSTALL any additional headers. We don't want an extra - #include slowing everybody down. - -* The solution should not unduly affect libc++ developers. The problem is limited - to installed versions of libc++ and the solution should be as well. - -* The solution should not modify any existing headers EXCEPT during installation. - It makes developers lives harder if they have to regenerate the libc++ headers - every time they are modified. - -* The solution should not make any of the libc++ headers dependent on - files generated by the build system. The headers should be able to compile - out of the box without any modification. - -* The solution should not have ANY effect on users who don't need special - configuration options. The vast majority of users will never need this so it - shouldn't cost them. - - -The Solution -============ - -When you first configure libc++ using CMake we check to see if we need to -capture any options. If we haven't been given any "persistent" options then -we do NOTHING. - -Otherwise we create a custom installation rule that modifies the installed __config -header. The rule first generates a dummy "__config_site" header containing the required -#defines. The contents of the dummy header are then prepended to the installed -__config header. By manually prepending the files we avoid the cost of an -extra #include and we allow the __config header to be ignorant of the extra -configuration all together. An example "__config" header generated when --DLIBCXX_ENABLE_THREADS=OFF is given to CMake would look something like: - -.. code-block:: cpp - - //===----------------------------------------------------------------------===// - // - // The LLVM Compiler Infrastructure - // - // This file is dual licensed under the MIT and the University of Illinois Open - // Source Licenses. See LICENSE.TXT for details. - // - //===----------------------------------------------------------------------===// - - #ifndef _LIBCPP_CONFIG_SITE - #define _LIBCPP_CONFIG_SITE - - /* #undef _LIBCPP_HAS_NO_GLOBAL_FILESYSTEM_NAMESPACE */ - /* #undef _LIBCPP_HAS_NO_STDIN */ - /* #undef _LIBCPP_HAS_NO_STDOUT */ - #define _LIBCPP_HAS_NO_THREADS - /* #undef _LIBCPP_HAS_NO_MONOTONIC_CLOCK */ - /* #undef _LIBCPP_HAS_NO_THREAD_UNSAFE_C_FUNCTIONS */ - - #endif - // -*- C++ -*- - //===--------------------------- __config ---------------------------------===// - // - // The LLVM Compiler Infrastructure - // - // This file is dual licensed under the MIT and the University of Illinois Open - // Source Licenses. See LICENSE.TXT for details. - // - //===----------------------------------------------------------------------===// - - #ifndef _LIBCPP_CONFIG - #define _LIBCPP_CONFIG diff --git a/lib/libcxx/docs/DesignDocs/DebugMode.rst b/lib/libcxx/docs/DesignDocs/DebugMode.rst deleted file mode 100644 index 3b997d44607..00000000000 --- a/lib/libcxx/docs/DesignDocs/DebugMode.rst +++ /dev/null @@ -1,100 +0,0 @@ -========== -Debug Mode -========== - -.. contents:: - :local: - -.. _using-debug-mode: - -Using Debug Mode -================ - -Libc++ provides a debug mode that enables assertions meant to detect incorrect -usage of the standard library. By default these assertions are disabled but -they can be enabled using the ``_LIBCPP_DEBUG`` macro. - -**_LIBCPP_DEBUG** Macro ------------------------ - -**_LIBCPP_DEBUG**: - This macro is used to enable assertions and iterator debugging checks within - libc++. By default it is undefined. - - **Values**: ``0``, ``1`` - - Defining ``_LIBCPP_DEBUG`` to ``0`` or greater enables most of libc++'s - assertions. Defining ``_LIBCPP_DEBUG`` to ``1`` enables "iterator debugging" - which provides additional assertions about the validity of iterators used by - the program. - - Note that this option has no effect on libc++'s ABI - -**_LIBCPP_DEBUG_USE_EXCEPTIONS**: - When this macro is defined ``_LIBCPP_ASSERT`` failures throw - ``__libcpp_debug_exception`` instead of aborting. Additionally this macro - disables exception specifications on functions containing ``_LIBCPP_ASSERT`` - checks. This allows assertion failures to correctly throw through these - functions. - -Handling Assertion Failures ---------------------------- - -When a debug assertion fails the assertion handler is called via the -``std::__libcpp_debug_function`` function pointer. It is possible to override -this function pointer using a different handler function. Libc++ provides two -different assertion handlers, the default handler -``std::__libcpp_abort_debug_handler`` which aborts the program, and -``std::__libcpp_throw_debug_handler`` which throws an instance of -``std::__libcpp_debug_exception``. Libc++ can be changed to use the throwing -assertion handler as follows: - -.. code-block:: cpp - - #define _LIBCPP_DEBUG 1 - #include <string> - int main() { - std::__libcpp_debug_function = std::__libcpp_throw_debug_function; - try { - std::string::iterator bad_it; - std::string str("hello world"); - str.insert(bad_it, '!'); // causes debug assertion - } catch (std::__libcpp_debug_exception const&) { - return EXIT_SUCCESS; - } - return EXIT_FAILURE; - } - -Debug Mode Checks -================= - -Libc++'s debug mode offers two levels of checking. The first enables various -precondition checks throughout libc++. The second additionally enables -"iterator debugging" which checks the validity of iterators used by the program. - -Basic Checks -============ - -These checks are enabled when ``_LIBCPP_DEBUG`` is defined to either 0 or 1. - -The following checks are enabled by ``_LIBCPP_DEBUG``: - - * FIXME: Update this list - -Iterator Debugging Checks -========================= - -These checks are enabled when ``_LIBCPP_DEBUG`` is defined to 1. - -The following containers and STL classes support iterator debugging: - - * ``std::string`` - * ``std::vector<T>`` (``T != bool``) - * ``std::list`` - * ``std::unordered_map`` - * ``std::unordered_multimap`` - * ``std::unordered_set`` - * ``std::unordered_multiset`` - -The remaining containers do not currently support iterator debugging. -Patches welcome. diff --git a/lib/libcxx/docs/DesignDocs/FeatureTestMacros.rst b/lib/libcxx/docs/DesignDocs/FeatureTestMacros.rst deleted file mode 100644 index d55af96c674..00000000000 --- a/lib/libcxx/docs/DesignDocs/FeatureTestMacros.rst +++ /dev/null @@ -1,44 +0,0 @@ -=================== -Feature Test Macros -=================== - -.. contents:: - :local: - -Overview -======== - -Libc++ implements the C++ feature test macros as specified in the C++2a standard, -and before that in non-normative guiding documents (`See cppreference <https://en.cppreference.com/w/User:D41D8CD98F/feature_testing_macros>`) - -Design -====== - -Feature test macros are tricky to track, implement, test, and document correctly. -They must be available from a list of headers, they may have different values in -different dialects, and they may or may not be implemented by libc++. In order to -track all of these conditions correctly and easily, we want a Single Source of -Truth (SSoT) that defines each feature test macro, its values, the headers it -lives in, and whether or not is is implemented by libc++. From this SSoA we -have enough information to automatically generate the `<version>` header, -the tests, and the documentation. - -Therefore we maintain a SSoA in -`libcxx/test/std/language.support/support.limits/support.limits.general/generate_feature_test_macro_components.py` -which doubles as a script to generate the following components: - -* The `<version>` header. -* The version tests under `support.limits.general`. -* Documentation of libc++'s implementation of each macro. - -Usage -===== - -The `generate_feature_test_macro_components.py` script is used to track and -update feature test macros in libc++. - -Whenever a feature test macro is added or changed, the table should be updated -and the script should be re-ran. The script will clobber the existing test files -and the documentation and it will generate a new `<version>` header as a -temporary file. The generated `<version>` header should be merged with the -existing one.
\ No newline at end of file diff --git a/lib/libcxx/docs/DesignDocs/FileTimeType.rst b/lib/libcxx/docs/DesignDocs/FileTimeType.rst deleted file mode 100644 index 488ff174b34..00000000000 --- a/lib/libcxx/docs/DesignDocs/FileTimeType.rst +++ /dev/null @@ -1,494 +0,0 @@ -============== -File Time Type -============== - -.. contents:: - :local: - -.. _file-time-type-motivation: - -Motivation -========== - -The filesystem library provides interfaces for getting and setting the last -write time of a file or directory. The interfaces use the ``file_time_type`` -type, which is a specialization of ``chrono::time_point`` for the -"filesystem clock". According to [fs.filesystem.syn] - - trivial-clock is an implementation-defined type that satisfies the - Cpp17TrivialClock requirements ([time.clock.req]) and that is capable of - representing and measuring file time values. Implementations should ensure - that the resolution and range of file_time_type reflect the operating - system dependent resolution and range of file time values. - - -On POSIX systems, file times are represented using the ``timespec`` struct, -which is defined as follows: - -.. code-block:: cpp - - struct timespec { - time_t tv_sec; - long tv_nsec; - }; - -To represent the range and resolution of ``timespec``, we need to (A) have -nanosecond resolution, and (B) use more than 64 bits (assuming a 64 bit ``time_t``). - -As the standard requires us to use the ``chrono`` interface, we have to define -our own filesystem clock which specifies the period and representation of -the time points and duration it provides. It will look like this: - -.. code-block:: cpp - - struct _FilesystemClock { - using period = nano; - using rep = TBD; // What is this? - - using duration = chrono::duration<rep, period>; - using time_point = chrono::time_point<_FilesystemClock>; - - // ... // - }; - - using file_time_type = _FilesystemClock::time_point; - - -To get nanosecond resolution, we simply define ``period`` to be ``std::nano``. -But what type can we use as the arithmetic representation that is capable -of representing the range of the ``timespec`` struct? - -Problems To Consider -==================== - -Before considering solutions, let's consider the problems they should solve, -and how important solving those problems are: - - -Having a Smaller Range than ``timespec`` ----------------------------------------- - -One solution to the range problem is to simply reduce the resolution of -``file_time_type`` to be less than that of nanoseconds. This is what libc++'s -initial implementation of ``file_time_type`` did; it's also what -``std::system_clock`` does. As a result, it can represent time points about -292 thousand years on either side of the epoch, as opposed to only 292 years -at nanosecond resolution. - -``timespec`` can represent time points +/- 292 billion years from the epoch -(just in case you needed a time point 200 billion years before the big bang, -and with nanosecond resolution). - -To get the same range, we would need to drop our resolution to that of seconds -to come close to having the same range. - -This begs the question, is the range problem "really a problem"? Sane usages -of file time stamps shouldn't exceed +/- 300 years, so should we care to support it? - -I believe the answer is yes. We're not designing the filesystem time API, we're -providing glorified C++ wrappers for it. If the underlying API supports -a value, then we should too. Our wrappers should not place artificial restrictions -on users that are not present in the underlying filesystem. - -Having a smaller range that the underlying filesystem forces the -implementation to report ``value_too_large`` errors when it encounters a time -point that it can't represent. This can cause the call to ``last_write_time`` -to throw in cases where the user was confident the call should succeed. (See below) - - -.. code-block:: cpp - - #include <filesystem> - using namespace std::filesystem; - - // Set the times using the system interface. - void set_file_times(const char* path, struct timespec ts) { - timespec both_times[2]; - both_times[0] = ts; - both_times[1] = ts; - int result = ::utimensat(AT_FDCWD, path, both_times, 0); - assert(result != -1); - } - - // Called elsewhere to set the file time to something insane, and way - // out of the 300 year range we might expect. - void some_bad_persons_code() { - struct timespec new_times; - new_times.tv_sec = numeric_limits<time_t>::max(); - new_times.tv_nsec = 0; - set_file_times("/tmp/foo", new_times); // OK, supported by most FSes - } - - int main() { - path p = "/tmp/foo"; - file_status st = status(p); - if (!exists(st) || !is_regular_file(st)) - return 1; - if ((st.permissions() & perms::others_read) == perms::none) - return 1; - // It seems reasonable to assume this call should succeed. - file_time_type tp = last_write_time(p); // BAD! Throws value_too_large. - } - - -Having a Smaller Resolution than ``timespec`` ---------------------------------------------- - -As mentioned in the previous section, one way to solve the range problem -is by reducing the resolution. But matching the range of ``timespec`` using a -64 bit representation requires limiting the resolution to seconds. - -So we might ask: Do users "need" nanosecond precision? Is seconds not good enough? -I limit my consideration of the point to this: Why was it not good enough for -the underlying system interfaces? If it wasn't good enough for them, then it -isn't good enough for us. Our job is to match the filesystems range and -representation, not design it. - - -Having a Larger Range than ``timespec`` ----------------------------------------- - -We should also consider the opposite problem of having a ``file_time_type`` -that is able to represent a larger range than ``timespec``. At least in -this case ``last_write_time`` can be used to get and set all possible values -supported by the underlying filesystem; meaning ``last_write_time(p)`` will -never throw a overflow error when retrieving a value. - -However, this introduces a new problem, where users are allowed to attempt to -create a time point beyond what the filesystem can represent. Two particular -values which cause this are ``file_time_type::min()`` and -``file_time_type::max()``. As a result, the following code would throw: - -.. code-block:: cpp - - void test() { - last_write_time("/tmp/foo", file_time_type::max()); // Throws - last_write_time("/tmp/foo", file_time_type::min()); // Throws. - } - -Apart from cases explicitly using ``min`` and ``max``, I don't see users taking -a valid time point, adding a couple hundred billions of years in error, -and then trying to update a file's write time to that value very often. - -Compared to having a smaller range, this problem seems preferable. At least -now we can represent any time point the filesystem can, so users won't be forced -to revert back to system interfaces to avoid limitations in the C++ STL. - -I posit that we should only consider this concern *after* we have something -with at least the same range and resolution of the underlying filesystem. The -latter two problems are much more important to solve. - -Potential Solutions And Their Complications -=========================================== - -Source Code Portability Across Implementations ------------------------------------------------ - -As we've discussed, ``file_time_type`` needs a representation that uses more -than 64 bits. The possible solutions include using ``__int128_t``, emulating a -128 bit integer using a class, or potentially defining a ``timespec`` like -arithmetic type. All three will allow us to, at minimum, match the range -and resolution, and the last one might even allow us to match them exactly. - -But when considering these potential solutions we need to consider more than -just the values they can represent. We need to consider the effects they will -have on users and their code. For example, each of them breaks the following -code in some way: - -.. code-block:: cpp - - // Bug caused by an unexpected 'rep' type returned by count. - void print_time(path p) { - // __int128_t doesn't have streaming operators, and neither would our - // custom arithmetic types. - cout << last_write_time(p).time_since_epoch().count() << endl; - } - - // Overflow during creation bug. - file_time_type timespec_to_file_time_type(struct timespec ts) { - // woops! chrono::seconds and chrono::nanoseconds use a 64 bit representation - // this may overflow before it's converted to a file_time_type. - auto dur = seconds(ts.tv_sec) + nanoseconds(ts.tv_nsec); - return file_time_type(dur); - } - - file_time_type correct_timespec_to_file_time_type(struct timespec ts) { - // This is the correct version of the above example, where we - // avoid using the chrono typedefs as they're not sufficient. - // Can we expect users to avoid this bug? - using fs_seconds = chrono::duration<file_time_type::rep>; - using fs_nanoseconds = chrono::duration<file_time_type::rep, nano>; - auto dur = fs_seconds(ts.tv_sec) + fs_nanoseconds(tv.tv_nsec); - return file_time_type(dur); - } - - // Implicit truncation during conversion bug. - intmax_t get_time_in_seconds(path p) { - using fs_seconds = duration<file_time_type::rep, ratio<1, 1> >; - auto tp = last_write_time(p); - - // This works with truncation for __int128_t, but what does it do for - // our custom arithmetic types. - return duration_cast<fs_seconds>().count(); - } - - -Each of the above examples would require a user to adjust their filesystem code -to the particular eccentricities of the representation, hopefully only in such -a way that the code is still portable across implementations. - -At least some of the above issues are unavoidable, no matter what -representation we choose. But some representations may be quirkier than others, -and, as I'll argue later, using an actual arithmetic type (``__int128_t``) -provides the least aberrant behavior. - - -Chrono and ``timespec`` Emulation. ----------------------------------- - -One of the options we've considered is using something akin to ``timespec`` -to represent the ``file_time_type``. It only seems natural seeing as that's -what the underlying system uses, and because it might allow us to match -the range and resolution exactly. But would it work with chrono? And could -it still act at all like a ``timespec`` struct? - -For ease of consideration, let's consider what the implementation might -look like. - -.. code-block:: cpp - - struct fs_timespec_rep { - fs_timespec_rep(long long v) - : tv_sec(v / nano::den), tv_nsec(v % nano::den) - { } - private: - time_t tv_sec; - long tv_nsec; - }; - bool operator==(fs_timespec_rep, fs_timespec_rep); - fs_int128_rep operator+(fs_timespec_rep, fs_timespec_rep); - // ... arithmetic operators ... // - -The first thing to notice is that we can't construct ``fs_timespec_rep`` like -a ``timespec`` by passing ``{secs, nsecs}``. Instead we're limited to -constructing it from a single 64 bit integer. - -We also can't allow the user to inspect the ``tv_sec`` or ``tv_nsec`` values -directly. A ``chrono::duration`` represents its value as a tick period and a -number of ticks stored using ``rep``. The representation is unaware of the -tick period it is being used to represent, but ``timespec`` is setup to assume -a nanosecond tick period; which is the only case where the names ``tv_sec`` -and ``tv_nsec`` match the values they store. - -When we convert a nanosecond duration to seconds, ``fs_timespec_rep`` will -use ``tv_sec`` to represent the number of giga seconds, and ``tv_nsec`` the -remaining seconds. Let's consider how this might cause a bug were users allowed -to manipulate the fields directly. - -.. code-block:: cpp - - template <class Period> - timespec convert_to_timespec(duration<fs_time_rep, Period> dur) { - fs_timespec_rep rep = dur.count(); - return {rep.tv_sec, rep.tv_nsec}; // Oops! Period may not be nanoseconds. - } - - template <class Duration> - Duration convert_to_duration(timespec ts) { - Duration dur({ts.tv_sec, ts.tv_nsec}); // Oops! Period may not be nanoseconds. - return file_time_type(dur); - file_time_type tp = last_write_time(p); - auto dur = - } - - time_t extract_seconds(file_time_type tp) { - // Converting to seconds is a silly bug, but I could see it happening. - using SecsT = chrono::duration<file_time_type::rep, ratio<1, 1>>; - auto secs = duration_cast<Secs>(tp.time_since_epoch()); - // tv_sec is now representing gigaseconds. - return secs.count().tv_sec; // Oops! - } - -Despite ``fs_timespec_rep`` not being usable in any manner resembling -``timespec``, it still might buy us our goal of matching its range exactly, -right? - -Sort of. Chrono provides a specialization point which specifies the minimum -and maximum values for a custom representation. It looks like this: - -.. code-block:: cpp - - template <> - struct duration_values<fs_timespec_rep> { - static fs_timespec_rep zero(); - static fs_timespec_rep min(); - static fs_timespec_rep max() { // assume friendship. - fs_timespec_rep val; - val.tv_sec = numeric_limits<time_t>::max(); - val.tv_nsec = nano::den - 1; - return val; - } - }; - -Notice that ``duration_values`` doesn't tell the representation what tick -period it's actually representing. This would indeed correctly limit the range -of ``duration<fs_timespec_rep, nano>`` to exactly that of ``timespec``. But -nanoseconds isn't the only tick period it will be used to represent. For -example: - -.. code-block:: cpp - - void test() { - using rep = file_time_type::rep; - using fs_nsec = duration<rep, nano>; - using fs_sec = duration<rep>; - fs_nsec nsecs(fs_seconds::max()); // Truncates - } - -Though the above example may appear silly, I think it follows from the incorrect -notion that using a ``timespec`` rep in chrono actually makes it act as if it -were an actual ``timespec``. - -Interactions with 32 bit ``time_t`` ------------------------------------ - -Up until now we've only be considering cases where ``time_t`` is 64 bits, but what -about 32 bit systems/builds where ``time_t`` is 32 bits? (this is the common case -for 32 bit builds). - -When ``time_t`` is 32 bits, we can implement ``file_time_type`` simply using 64-bit -``long long``. There is no need to get either ``__int128_t`` or ``timespec`` emulation -involved. And nor should we, as it would suffer from the numerous complications -described by this paper. - -Obviously our implementation for 32-bit builds should act as similarly to the -64-bit build as possible. Code which compiles in one, should compile in the other. -This consideration is important when choosing between ``__int128_t`` and -emulating ``timespec``. The solution which provides the most uniformity with -the least eccentricity is the preferable one. - -Summary -======= - -The ``file_time_type`` time point is used to represent the write times for files. -Its job is to act as part of a C++ wrapper for less ideal system interfaces. The -underlying filesystem uses the ``timespec`` struct for the same purpose. - -However, the initial implementation of ``file_time_type`` could not represent -either the range or resolution of ``timespec``, making it unsuitable. Fixing -this requires an implementation which uses more than 64 bits to store the -time point. - -We primarily considered two solutions: Using ``__int128_t`` and using a -arithmetic emulation of ``timespec``. Each has its pros and cons, and both -come with more than one complication. - -The Potential Solutions ------------------------ - -``long long`` - The Status Quo -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Pros: - -* As a type ``long long`` plays the nicest with others: - - * It works with streaming operators and other library entities which support - builtin integer types, but don't support ``__int128_t``. - * Its the representation used by chrono's ``nanosecond`` and ``second`` typedefs. - -Cons: - -* It cannot provide the same resolution as ``timespec`` unless we limit it - to a range of +/- 300 years from the epoch. -* It cannot provide the same range as ``timespec`` unless we limit its resolution - to seconds. -* ``last_write_time`` has to report an error when the time reported by the filesystem - is unrepresentable. - -__int128_t -~~~~~~~~~~~ - -Pros: - -* It is an integer type. -* It makes the implementation simple and efficient. -* Acts exactly like other arithmetic types. -* Can be implicitly converted to a builtin integer type by the user. - - * This is important for doing things like: - - .. code-block:: cpp - - void c_interface_using_time_t(const char* p, time_t); - - void foo(path p) { - file_time_type tp = last_write_time(p); - time_t secs = duration_cast<seconds>(tp.time_since_epoch()).count(); - c_interface_using_time_t(p.c_str(), secs); - } - -Cons: - -* It isn't always available (but on 64 bit machines, it normally is). -* It causes ``file_time_type`` to have a larger range than ``timespec``. -* It doesn't always act the same as other builtin integer types. For example - with ``cout`` or ``to_string``. -* Allows implicit truncation to 64 bit integers. -* It can be implicitly converted to a builtin integer type by the user, - truncating its value. - -Arithmetic ``timespec`` Emulation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Pros: - -* It has the exact same range and resolution of ``timespec`` when representing - a nanosecond tick period. -* It's always available, unlike ``__int128_t``. - -Cons: - -* It has a larger range when representing any period longer than a nanosecond. -* Doesn't actually allow users to use it like a ``timespec``. -* The required representation of using ``tv_sec`` to store the giga tick count - and ``tv_nsec`` to store the remainder adds nothing over a 128 bit integer, - but complicates a lot. -* It isn't a builtin integer type, and can't be used anything like one. -* Chrono can be made to work with it, but not nicely. -* Emulating arithmetic classes come with their own host of problems regarding - overload resolution (Each operator needs three SFINAE constrained versions of - it in order to act like builtin integer types). -* It offers little over simply using ``__int128_t``. -* It acts the most differently than implementations using an actual integer type, - which has a high chance of breaking source compatibility. - - -Selected Solution - Using ``__int128_t`` -========================================= - -The solution I selected for libc++ is using ``__int128_t`` when available, -and otherwise falling back to using ``long long`` with nanosecond precision. - -When ``__int128_t`` is available, or when ``time_t`` is 32-bits, the implementation -provides same resolution and a greater range than ``timespec``. Otherwise -it still provides the same resolution, but is limited to a range of +/- 300 -years. This final case should be rather rare, as ``__int128_t`` -is normally available in 64-bit builds, and ``time_t`` is normally 32-bits -during 32-bit builds. - -Although falling back to ``long long`` and nanosecond precision is less than -ideal, it also happens to be the implementation provided by both libstdc++ -and MSVC. (So that makes it better, right?) - -Although the ``timespec`` emulation solution is feasible and would largely -do what we want, it comes with too many complications, potential problems -and discrepancies when compared to "normal" chrono time points and durations. - -An emulation of a builtin arithmetic type using a class is never going to act -exactly the same, and the difference will be felt by users. It's not reasonable -to expect them to tolerate and work around these differences. And once -we commit to an ABI it will be too late to change. Committing to this seems -risky. - -Therefore, ``__int128_t`` seems like the better solution. diff --git a/lib/libcxx/docs/DesignDocs/ThreadingSupportAPI.rst b/lib/libcxx/docs/DesignDocs/ThreadingSupportAPI.rst deleted file mode 100644 index 330ce74cf77..00000000000 --- a/lib/libcxx/docs/DesignDocs/ThreadingSupportAPI.rst +++ /dev/null @@ -1,83 +0,0 @@ -===================== -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 -========================== - -libc++ can be compiled with its internal threading API delegating 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 systems (e.g. pthread) supported in ``__threading_support`` -header. Therefore, the main purpose of this option is to allow testing of this -particular configuration of the library without being tied to a vendor-specific -threading system. This option is only meant to be used by libc++ library -developers. - -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_API_WIN32** - This macro is defined when libc++ should use Win32 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. diff --git a/lib/libcxx/docs/DesignDocs/VisibilityMacros.rst b/lib/libcxx/docs/DesignDocs/VisibilityMacros.rst deleted file mode 100644 index d0d4f0adb22..00000000000 --- a/lib/libcxx/docs/DesignDocs/VisibilityMacros.rst +++ /dev/null @@ -1,218 +0,0 @@ -======================== -Symbol Visibility Macros -======================== - -.. contents:: - :local: - -Overview -======== - -Libc++ uses various "visibility" macros in order to provide a stable ABI in -both the library and the headers. These macros work by changing the -visibility and inlining characteristics of the symbols they are applied to. - -Visibility Macros -================= - -**_LIBCPP_HIDDEN** - Mark a symbol as hidden so it will not be exported from shared libraries. - -**_LIBCPP_FUNC_VIS** - Mark a symbol as being exported by the libc++ library. This attribute must - be applied to the declaration of all functions exported by the libc++ dylib. - -**_LIBCPP_EXPORTED_FROM_ABI** - Mark a symbol as being exported by the libc++ library. This attribute may - only be applied to objects defined in the libc++ runtime library. On Windows, - this macro applies `dllimport`/`dllexport` to the symbol, and on other - platforms it gives the symbol default visibility. - -**_LIBCPP_OVERRIDABLE_FUNC_VIS** - Mark a symbol as being exported by the libc++ library, but allow it to be - overridden locally. On non-Windows, this is equivalent to `_LIBCPP_FUNC_VIS`. - This macro is applied to all `operator new` and `operator delete` overloads. - - **Windows Behavior**: Any symbol marked `dllimport` cannot be overridden - locally, since `dllimport` indicates the symbol should be bound to a separate - DLL. All `operator new` and `operator delete` overloads are required to be - locally overridable, and therefore must not be marked `dllimport`. On Windows, - this macro therefore expands to `__declspec(dllexport)` when building the - library and has an empty definition otherwise. - -**_LIBCPP_HIDE_FROM_ABI** - Mark a function as not being part of the ABI of any final linked image that - uses it. - -**_LIBCPP_HIDE_FROM_ABI_AFTER_V1** - Mark a function as being hidden from the ABI (per `_LIBCPP_HIDE_FROM_ABI`) - when libc++ is built with an ABI version after ABI v1. This macro is used to - maintain ABI compatibility for symbols that have been historically exported - by libc++ in v1 of the ABI, but that we don't want to export in the future. - - This macro works as follows. When we build libc++, we either hide the symbol - from the ABI (if the symbol is not part of the ABI in the version we're - building), or we leave it included. From user code (i.e. when we're not - building libc++), the macro always marks symbols as internal so that programs - built using new libc++ headers stop relying on symbols that are removed from - the ABI in a future version. Each time we release a new stable version of the - ABI, we should create a new _LIBCPP_HIDE_FROM_ABI_AFTER_XXX macro, and we can - use it to start removing symbols from the ABI after that stable version. - -**_LIBCPP_HIDE_FROM_ABI_PER_TU** - This macro controls whether symbols hidden from the ABI with `_LIBCPP_HIDE_FROM_ABI` - are local to each translation unit in addition to being local to each final - linked image. This macro is defined to either 0 or 1. When it is defined to - 1, translation units compiled with different versions of libc++ can be linked - together, since all non ABI-facing functions are local to each translation unit. - This allows static archives built with different versions of libc++ to be linked - together. This also means that functions marked with `_LIBCPP_HIDE_FROM_ABI` - are not guaranteed to have the same address across translation unit boundaries. - - When the macro is defined to 0, there is no guarantee that translation units - compiled with different versions of libc++ can interoperate. However, this - leads to code size improvements, since non ABI-facing functions can be - deduplicated across translation unit boundaries. - - This macro can be defined by users to control the behavior they want from - libc++. The default value of this macro (0 or 1) is controlled by whether - `_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT` is defined, which is intended to - be used by vendors only (see below). - -**_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT** - This macro controls the default value for `_LIBCPP_HIDE_FROM_ABI_PER_TU`. - When the macro is defined, per TU ABI insulation is enabled by default, and - `_LIBCPP_HIDE_FROM_ABI_PER_TU` is defined to 1 unless overridden by users. - Otherwise, per TU ABI insulation is disabled by default, and - `_LIBCPP_HIDE_FROM_ABI_PER_TU` is defined to 0 unless overridden by users. - - This macro is intended for vendors to control whether they want to ship - libc++ with per TU ABI insulation enabled by default. Users can always - control the behavior they want by defining `_LIBCPP_HIDE_FROM_ABI_PER_TU` - appropriately. - - By default, this macro is not defined, which means that per TU ABI insulation - is not provided unless explicitly overridden by users. - -**_LIBCPP_TYPE_VIS** - Mark a type's typeinfo, vtable and members as having default visibility. - This attribute cannot be used on class templates. - -**_LIBCPP_TEMPLATE_VIS** - Mark a type's typeinfo and vtable as having default visibility. - This macro has no effect on the visibility of the type's member functions. - - **GCC Behavior**: GCC does not support Clang's `type_visibility(...)` - attribute. With GCC the `visibility(...)` attribute is used and member - functions are affected. - - **Windows Behavior**: DLLs do not support dllimport/export on class templates. - The macro has an empty definition on this platform. - - -**_LIBCPP_ENUM_VIS** - Mark the typeinfo of an enum as having default visibility. This attribute - should be applied to all enum declarations. - - **Windows Behavior**: DLLs do not support importing or exporting enumeration - typeinfo. The macro has an empty definition on this platform. - - **GCC Behavior**: GCC un-hides the typeinfo for enumerations by default, even - if `-fvisibility=hidden` is specified. Additionally applying a visibility - attribute to an enum class results in a warning. The macro has an empty - definition with GCC. - -**_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS** - Mark the member functions, typeinfo, and vtable of the type named in - a `_LIBCPP_EXTERN_TEMPLATE` declaration as being exported by the libc++ library. - This attribute must be specified on all extern class template declarations. - - This macro is used to override the `_LIBCPP_TEMPLATE_VIS` attribute - specified on the primary template and to export the member functions produced - by the explicit instantiation in the dylib. - - **GCC Behavior**: GCC ignores visibility attributes applied the type in - extern template declarations and applying an attribute results in a warning. - However since `_LIBCPP_TEMPLATE_VIS` is the same as - `__attribute__((visibility("default"))` the visibility is already correct. - The macro has an empty definition with GCC. - - **Windows Behavior**: `extern template` and `dllexport` are fundamentally - incompatible *on a class template* on Windows; the former suppresses - instantiation, while the latter forces it. Specifying both on the same - declaration makes the class template be instantiated, which is not desirable - inside headers. This macro therefore expands to `dllimport` outside of libc++ - but nothing inside of it (rather than expanding to `dllexport`); instead, the - explicit instantiations themselves are marked as exported. Note that this - applies *only* to extern *class* templates. Extern *function* templates obey - regular import/export semantics, and applying `dllexport` directly to the - extern template declaration (i.e. using `_LIBCPP_FUNC_VIS`) is the correct - thing to do for them. - -**_LIBCPP_CLASS_TEMPLATE_INSTANTIATION_VIS** - Mark the member functions, typeinfo, and vtable of an explicit instantiation - of a class template as being exported by the libc++ library. This attribute - must be specified on all class template explicit instantiations. - - It is only necessary to mark the explicit instantiation itself (as opposed to - the extern template declaration) as exported on Windows, as discussed above. - On all other platforms, this macro has an empty definition. - -**_LIBCPP_METHOD_TEMPLATE_IMPLICIT_INSTANTIATION_VIS** - Mark a symbol as hidden so it will not be exported from shared libraries. This - is intended specifically for method templates of either classes marked with - `_LIBCPP_TYPE_VIS` or classes with an extern template instantiation - declaration marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS`. - - When building libc++ with hidden visibility, we want explicit template - instantiations to export members, which is consistent with existing Windows - behavior. We also want classes annotated with `_LIBCPP_TYPE_VIS` to export - their members, which is again consistent with existing Windows behavior. - Both these changes are necessary for clients to be able to link against a - libc++ DSO built with hidden visibility without encountering missing symbols. - - An unfortunate side effect, however, is that method templates of classes - either marked `_LIBCPP_TYPE_VIS` or with extern template instantiation - declarations marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` also get default - visibility when instantiated. These methods are often implicitly instantiated - inside other libraries which use the libc++ headers, and will therefore end up - being exported from those libraries, since those implicit instantiations will - receive default visibility. This is not acceptable for libraries that wish to - control their visibility, and led to PR30642. - - Consequently, all such problematic method templates are explicitly marked - either hidden (via this macro) or inline, so that they don't leak into client - libraries. The problematic methods were found by running - `bad-visibility-finder <https://github.com/smeenai/bad-visibility-finder>`_ - against the libc++ headers after making `_LIBCPP_TYPE_VIS` and - `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` expand to default visibility. - -**_LIBCPP_EXCEPTION_ABI** - Mark the member functions, typeinfo, and vtable of the type as being exported - by the libc++ library. This macro must be applied to all *exception types*. - Exception types should be defined directly in namespace `std` and not the - versioning namespace. This allows throwing and catching some exception types - between libc++ and libstdc++. - -**_LIBCPP_INTERNAL_LINKAGE** - Mark the affected entity as having internal linkage (i.e. the `static` - keyword in C). This is only a best effort: when the `internal_linkage` - attribute is not available, we fall back to forcing the function to be - inlined, which approximates internal linkage since an externally visible - symbol is never generated for that function. This is an internal macro - used as an implementation detail by other visibility macros. Never mark - a function or a class with this macro directly. - -**_LIBCPP_ALWAYS_INLINE** - Forces inlining of the function it is applied to. For visibility purposes, - this macro is used to make sure that an externally visible symbol is never - generated in an object file when the `internal_linkage` attribute is not - available. This is an internal macro used by other visibility macros, and - it should not be used directly. - -Links -===== - -* `[cfe-dev] Visibility in libc++ - 1 <http://lists.llvm.org/pipermail/cfe-dev/2013-July/030610.html>`_ -* `[cfe-dev] Visibility in libc++ - 2 <http://lists.llvm.org/pipermail/cfe-dev/2013-August/031195.html>`_ -* `[libcxx] Visibility fixes for Windows <http://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20130805/085461.html>`_ |