diff options
author | Roman Lebedev <lebedev.ri@gmail.com> | 2018-09-22 17:54:48 +0000 |
---|---|---|
committer | Roman Lebedev <lebedev.ri@gmail.com> | 2018-09-22 17:54:48 +0000 |
commit | bb97d613f33c797b97aeb761e0ef17ae9166befd (patch) | |
tree | d59ef72004fb66c20324f6208fcbb67fa8580986 /libcxx/docs | |
parent | b3223f30ce9e2a0871d1cbe571a63a0afded8478 (diff) |
[libc++] Add _LIBCPP_ENABLE_NODISCARD and _LIBCPP_NODISCARD_EXT to allow pre-C++2a [[nodiscard]]
Summary:
The `[[nodiscard]]` attribute is intended to help users find bugs where
function return values are ignored when they shouldn't be. After C++17 the
C++ standard has started to declared such library functions as `[[nodiscard]]`.
However, this application is limited and applies only to dialects after C++17.
Users who want help diagnosing misuses of STL functions may desire a more
liberal application of `[[nodiscard]]`.
For this reason libc++ provides an extension that does just that! The
extension must be enabled by defining `_LIBCPP_ENABLE_NODISCARD`. The extended
applications of `[[nodiscard]]` takes two forms:
1. Backporting `[[nodiscard]]` to entities declared as such by the
standard in newer dialects, but not in the present one.
2. Extended applications of `[[nodiscard]]`, at the libraries discretion,
applied to entities never declared as such by the standard.
Users may also opt-out of additional applications `[[nodiscard]]` using
additional macros.
Applications of the first form, which backport `[[nodiscard]]` from a newer
dialect may be disabled using macros specific to the dialect it was added. For
example `_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17`.
Applications of the second form, which are pure extensions, may be disabled
by defining `_LIBCPP_DISABLE_NODISCARD_EXT`.
This patch was originally written by me (Roman Lebedev),
then but then reworked by Eric Fiselier.
Reviewers: mclow.lists, thakis, EricWF
Reviewed By: thakis, EricWF
Subscribers: llvm-commits, mclow.lists, lebedev.ri, EricWF, rjmccall, Quuxplusone, cfe-commits, christof
Differential Revision: https://reviews.llvm.org/D45179
Diffstat (limited to 'libcxx/docs')
-rw-r--r-- | libcxx/docs/UsingLibcxx.rst | 70 |
1 files changed, 70 insertions, 0 deletions
diff --git a/libcxx/docs/UsingLibcxx.rst b/libcxx/docs/UsingLibcxx.rst index e10a27c598a..993c8d7c41e 100644 --- a/libcxx/docs/UsingLibcxx.rst +++ b/libcxx/docs/UsingLibcxx.rst @@ -226,6 +226,21 @@ thread safety annotations. replacement scenarios from working, e.g. replacing `operator new` and expecting a non-replaced `operator new[]` to call the replaced `operator new`. +**_LIBCPP_ENABLE_NODISCARD**: + Allow the library to add ``[[nodiscard]]`` attributes to entities not specified + as ``[[nodiscard]]`` by the current language dialect. This includes + backporting applications of ``[[nodiscard]]`` from newer dialects and + additional extended applications at the discretion of the library. All + additional applications of ``[[nodiscard]]`` are disabled by default. + See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` for + more information. + +**_LIBCPP_DISABLE_NODISCARD_EXT**: + This macro prevents the library from applying ``[[nodiscard]]`` to entities + purely as an extension. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` + for more information. + + C++17 Specific Configuration Macros ----------------------------------- **_LIBCPP_ENABLE_CXX17_REMOVED_FEATURES**: @@ -238,3 +253,58 @@ C++17 Specific Configuration Macros **_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**: This macro is used to re-enable `std::auto_ptr` in C++17. + +C++2a Specific Configuration Macros: +------------------------------------ +**_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17**: + This macro can be used to disable diagnostics emitted from functions marked + ``[[nodiscard]]`` in dialects after C++17. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` + for more information. + + +Libc++ Extensions +================= + +This section documents various extensions provided by libc++, how they're +provided, and any information regarding how to use them. + +.. _nodiscard extension: + +Extended applications of ``[[nodiscard]]`` +------------------------------------------ + +The ``[[nodiscard]]`` attribute is intended to help users find bugs where +function return values are ignored when they shouldn't be. After C++17 the +C++ standard has started to declared such library functions as ``[[nodiscard]]``. +However, this application is limited and applies only to dialects after C++17. +Users who want help diagnosing misuses of STL functions may desire a more +liberal application of ``[[nodiscard]]``. + +For this reason libc++ provides an extension that does just that! The +extension must be enabled by defining ``_LIBCPP_ENABLE_NODISCARD``. The extended +applications of ``[[nodiscard]]`` takes two forms: + +1. Backporting ``[[nodiscard]]`` to entities declared as such by the + standard in newer dialects, but not in the present one. + +2. Extended applications of ``[[nodiscard]]``, at the libraries discretion, + applied to entities never declared as such by the standard. + +Users may also opt-out of additional applications ``[[nodiscard]]`` using +additional macros. + +Applications of the first form, which backport ``[[nodiscard]]`` from a newer +dialect may be disabled using macros specific to the dialect it was added. For +example ``_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17``. + +Applications of the second form, which are pure extensions, may be disabled +by defining ``_LIBCPP_DISABLE_NODISCARD_EXT``. + + +Entities declared with ``_LIBCPP_NODISCARD_EXT`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section lists all extended applications of ``[[nodiscard]]`` to entities +which no dialect declares as such (See the second form described above). + +* ``get_temporary_buffer`` |