summaryrefslogtreecommitdiffstats
path: root/docs/LanguageExtensions.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/LanguageExtensions.rst')
-rw-r--r--docs/LanguageExtensions.rst32
1 files changed, 32 insertions, 0 deletions
diff --git a/docs/LanguageExtensions.rst b/docs/LanguageExtensions.rst
index 0d358ad51a..e155cefb78 100644
--- a/docs/LanguageExtensions.rst
+++ b/docs/LanguageExtensions.rst
@@ -2697,6 +2697,38 @@ The ``__declspec`` style syntax is also supported:
A single push directive accepts only one attribute regardless of the syntax
used.
+Because multiple push directives can be nested, if you're writing a macro that
+expands to ``_Pragma("clang attribute")`` it's good hygiene (though not
+required) to add a namespace to your push/pop directives. A pop directive with a
+namespace will pop the innermost push that has that same namespace. This will
+ensure that another macro's ``pop`` won't inadvertently pop your attribute. Note
+that an ``pop`` without a namespace will pop the innermost ``push`` without a
+namespace. ``push``es with a namespace can only be popped by ``pop`` with the
+same namespace. For instance:
+
+.. code-block:: c++
+
+ #define ASSUME_NORETURN_BEGIN _Pragma("clang attribute AssumeNoreturn.push ([[noreturn]], apply_to = function)")
+ #define ASSUME_NORETURN_END _Pragma("clang attribute AssumeNoreturn.pop")
+
+ #define ASSUME_UNAVAILABLE_BEGIN _Pragma("clang attribute Unavailable.push (__attribute__((unavailable)), apply_to=function)")
+ #define ASSUME_UNAVAILABLE_END _Pragma("clang attribute Unavailable.pop")
+
+
+ ASSUME_NORETURN_BEGIN
+ ASSUME_UNAVAILABLE_BEGIN
+ void function(); // function has [[noreturn]] and __attribute__((unavailable))
+ ASSUME_NORETURN_END
+ void other_function(); // function has __attribute__((unavailable))
+ ASSUME_UNAVAILABLE_END
+
+Without the namespaces on the macros, ``other_function`` will be annotated with
+``[[noreturn]]`` instead of ``__attribute__((unavailable))``. This may seem like
+a contrived example, but its very possible for this kind of situation to appear
+in real code if the pragmas are spread out across a large file. You can test if
+your version of clang supports namespaces on ``#pragma clang attribute`` with
+``__has_extension(pragma_clang_attribute_namespaces)``.
+
Subject Match Rules
-------------------