diff options
Diffstat (limited to 'libcxx/docs')
| -rw-r--r-- | libcxx/docs/Hardening.rst | 9 | ||||
| -rw-r--r-- | libcxx/docs/ReleaseNotes/20.rst | 33 | ||||
| -rw-r--r-- | libcxx/docs/TestingLibcxx.rst | 23 |
3 files changed, 62 insertions, 3 deletions
diff --git a/libcxx/docs/Hardening.rst b/libcxx/docs/Hardening.rst index 4002f40..d399b94 100644 --- a/libcxx/docs/Hardening.rst +++ b/libcxx/docs/Hardening.rst @@ -311,7 +311,10 @@ ABI configuration. ABI options ----------- -Vendors can use the following ABI options to enable additional hardening checks: +Vendors can use some ABI options at CMake configuration time (when building libc++ +itself) to enable additional hardening checks. This is done by passing these +macros as ``-DLIBCXX_ABI_DEFINES="_LIBCPP_ABI_FOO;_LIBCPP_ABI_BAR;etc"`` at +CMake configuration time. The available options are: - ``_LIBCPP_ABI_BOUNDED_ITERATORS`` -- changes the iterator type of select containers (see below) to a bounded iterator that keeps track of whether it's @@ -341,7 +344,7 @@ Vendors can use the following ABI options to enable additional hardening checks: ABI impact: changes the iterator type of ``vector`` (except ``vector<bool>``). -- ``_LIBCPP_ABI_BOUNDED_UNIQUE_PTR``` -- tracks the bounds of the array stored inside +- ``_LIBCPP_ABI_BOUNDED_UNIQUE_PTR`` -- tracks the bounds of the array stored inside a ``std::unique_ptr<T[]>``, allowing it to trap when accessed out-of-bounds. This requires the ``std::unique_ptr`` to be created using an API like ``std::make_unique`` or ``std::make_unique_for_overwrite``, otherwise the bounds information is not available @@ -407,7 +410,7 @@ Hardened containers status - ✅ - ❌ * - ``forward_list`` - - ❌ + - ✅ - ❌ * - ``deque`` - ✅ diff --git a/libcxx/docs/ReleaseNotes/20.rst b/libcxx/docs/ReleaseNotes/20.rst index c8a07fb..ecfbaa5 100644 --- a/libcxx/docs/ReleaseNotes/20.rst +++ b/libcxx/docs/ReleaseNotes/20.rst @@ -73,6 +73,39 @@ Improvements and New Features optimized, resulting in a performance improvement of up to 2x for trivial element types (e.g., `std::vector<int>`), and up to 3.4x for non-trivial element types (e.g., `std::vector<std::vector<int>>`). +- On Windows, ``<system_error>``'s ``std::system_category`` is now distinct from ``std::generic_category``. The behavior + on other operating systems is unchanged. + + On Windows -- unlike on Unix systems -- the libc and system APIs use distinct error codes. The libc functions return + ``errno.h`` error codes via the ``errno`` global, while Win32 API functions return ``winerror.h`` error codes via + ``GetLastError()``. + + The C++ standard's ``std::error_code`` and ``std::error_category`` functionality was designed to support multiple + error domains, precisely in order to handle situations such as this. However, libc++ formerly treated + ``generic_category()`` and ``system_category()`` as equivalent, even on Windows. It now implements the intended split, + where ``system_category`` represents native ``winerror.h`` error codes, and ``generic_category`` represents libc error + codes (and, equivalently, ``std::errc::*`` errors). + + This change enables code like ``std::error_code(GetLastError(), std::system_category()) == + std::errc::invalid_argument`` to function as desired: constructing an ``error_code`` with the Windows error number in + the "system" category, and then mapping it to a generic code with ``error_condition``, for comparison with the + ``std::errc`` constant. + + This is an incompatible change: ``std::error_code(ENOSYS, std::system_category()) == + std::errc::function_not_supported`` would formerly have returned true, but now returns false on Windows. Code + providing a number from the ``errno.h`` domain should be migrated to construct a ``generic_category`` error_code, + instead. (E.g., use ``std::error_code(ENOSYS, std::generic_category())``). The new behavior matches MSVC. + +- On Windows, the ``std::filesystem`` library now returns the Win32 ``system_category`` error codes, where it's feasible + to do so. This allows interrogation and reporting of the original error code, which is useful if multiple Windows + errors map to a single generic error (such as with ``std::errc::no_such_file_or_directory``). + + This is also a slightly-incompatible API change: code inspecting the raw integer value from the returned error_code + expecting an integer from ``generic_category`` (e.g. ``err.value() == ENOTDIR``) will not work as desired. Instead, + such code should use the comparison operators which implicitly handle eror mappings, ``err == + std::errc::not_a_directory``, or use ``err.default_error_condition()`` to map to an ``error_condition``, and then test + its ``value()`` and ``category()``. + Deprecations and Removals ------------------------- diff --git a/libcxx/docs/TestingLibcxx.rst b/libcxx/docs/TestingLibcxx.rst index cf092fa..e98b96b 100644 --- a/libcxx/docs/TestingLibcxx.rst +++ b/libcxx/docs/TestingLibcxx.rst @@ -459,6 +459,29 @@ we only want to make sure they don't rot. Do not rely on the results of benchmar run through ``check-cxx`` for anything, instead run the benchmarks manually using the instructions for running individual tests. +If you want to compare the results of different benchmark runs, we recommend using the +``libcxx-compare-benchmarks`` helper tool. First, configure CMake in a build directory +and run the benchmark: + +.. code-block:: bash + + $ cmake -S runtimes -B <build1> [...] + $ libcxx/utils/libcxx-lit <build1> libcxx/test/benchmarks/string.bench.cpp --param optimization=speed + +Then, do the same for the second configuration you want to test. Use a different build +directory for that configuration: + +.. code-block:: bash + + $ cmake -S runtimes -B <build2> [...] + $ libcxx/utils/libcxx-lit <build2> libcxx/test/benchmarks/string.bench.cpp --param optimization=speed + +Finally, use ``libcxx-compare-benchmarks`` to compare both: + +.. code-block:: bash + + $ libcxx/utils/libcxx-compare-benchmarks <build1> <build2> libcxx/test/benchmarks/string.bench.cpp + .. _`Google Benchmark`: https://github.com/google/benchmark .. _testing-hardening-assertions: |