[clang] Add clang/docs/FunctionEffectAnalysis.rst. (PR #109855)

[via cfe-commits]

================
@@ -0,0 +1,544 @@
+========================
+Function Effect Analysis
+========================
+
+.. contents::
+  :depth: 3
+  :local:
+
+
+Introduction
+============
+
+Clang Function Effect Analysis is a language extension which can warn about "unsafe"
+constructs. The feature is currently tailored for the Performance Constraint attributes,
+``nonblocking`` and ``nonallocating``; functions with these attributes are verified as not
+containing any language constructs or calls to other functions which violate the constraint.
+(See :doc:`AttributeReference`.)
+
+
+The ``nonblocking`` and ``nonallocating`` attributes
+====================================================
+
+Attribute syntax
+----------------
+
+The ``nonblocking`` and ``nonallocating`` attributes apply to function types, allowing them to be
+attached to functions, blocks, function pointers, lambdas, and member functions.
+
+.. code-block:: c++
+
+  // Functions
+  void nonblockingFunction() [[clang::nonblocking]];
+  void nonallocatingFunction() [[clang::nonallocating]];
+
+  // Function pointers
+  void (*nonblockingFunctionPtr)() [[clang::nonblocking]];
+
+  // Typedefs, type aliases.
+  typedef void (*NBFunctionPtrTypedef)() [[clang::nonblocking]];
+  using NBFunctionPtrTypeAlias_gnu = __attribute__((nonblocking)) void (*)();
+  using NBFunctionPtrTypeAlias_std = void (*)() [[clang::nonblocking]];
+
+  // C++ methods
+  struct Struct {
+    void NBMethod() [[clang::nonblocking]];
+  };
+
+  // C++ lambdas
+  auto nbLambda = []() [[clang::nonblocking]] {};
+
+  // Blocks
+  void (^nbBlock)() = ^() [[clang::nonblocking]] {};
+
+The attribute applies only to the function itself. In particular, it does not apply to any nested
+functions or declarations, such as blocks, lambdas, and local classes.
+
+This document uses the C++/C23 syntax ``[[clang::nonblocking]]``, since it parallels the placement 
+of the ``noexcept`` specifier, and the attributes have other similarities to ``noexcept``. The GNU
+``__attribute__((nonblocking))`` syntax is also supported. Note that it requires a different 
+placement on a C++ type alias.
+
+Like ``noexcept``, ``nonblocking`` and ``nonallocating`` have an optional argument, a compile-time
+constant boolean expression. By default, the argument is ``true``, so ``[[clang::nonblocking]]``
+is equivalent to ``[[clang::nonblocking(true)]]``, and declares the function type as never locking.
+
+
+Attribute semantics
+-------------------
+
+Together with ``noexcept``, the ``nonallocating`` and ``nonblocking`` attributes define an ordered
+series of performance constraints. From weakest to strongest:
+
+- ``noexcept`` (as per the C++ standard): The function type will never throw an exception.
+- ``nonallocating``: The function type will never allocate memory on the heap, and never throw an
+  exception.
+- ``nonblocking``: The function type will never block on a lock, never allocate memory on the heap,
+  and never throw an exception.
+
+``nonblocking`` includes the ``nonallocating`` guarantee. 
+
+While ``nonblocking`` and ``nonallocating`` are conceptually a superset of ``noexcept``, neither
+attribute implicitly specifies ``noexcept``. Further, ``noexcept`` has a specified runtime behavior of 
+aborting if an exception is thrown, while the ``nonallocating`` and ``nonblocking`` attributes are
+purely for compile-time analysis and have no potential runtime behavior. Nonetheless, Clang emits a
+warning if, in C++, a function is declared ``nonblocking`` or ``nonallocating`` without
+``noexcept``. This diagnostic is controlled by ``-Wperf-constraint-implies-noexcept``.
+
+Also, the ``nonblocking`` and ``blocking`` attributes do have special runtime behavior in code built
+with Clang's :doc:`RealtimeSanitizer`.
+
+``nonblocking(true)`` and ``nonallocating(true)`` apply to function *types*, and by extension, to
+function-like declarations. When applied to a declaration with a body, the compiler verifies the
+function, as described in the section "Analysis and warnings", below. Functions without an explicit
+performance constraint are not verified.
+
+``blocking`` and ``allocating`` are synonyms for ``nonblocking(false)`` and
+``nonallocating(false)``, respectively. They can be used on a function-like declaration to
+explicitly disable any potential inference of ``nonblocking`` or ``nonallocating`` during
+verification. (Inference is described later in this document). ``nonblocking(false)`` and
+``nonallocating(false)`` are legal, but superfluous  when applied to a function *type*.
+``float (int) [[nonblocking(false)]]`` and ``float (int)`` are identical types.
+
+For functions with no explicit performance constraint, the worst is assumed: the function
+allocates memory and potentially blocks, unless it can be inferred otherwise. This is detailed in the
+discussion of verification.
+
+The following example describes the meanings of all permutations of the two attributes and arguments:
+
+.. code-block:: c++
+
+  void nb1_na1() [[clang::nonblocking(true)]] [[clang::nonallocating(true)]];
+  // Valid; nonallocating(true) is superfluous but doesn't contradict the guarantee.
+
+  void nb1_na0() [[clang::nonblocking(true)]] [[clang::nonallocating(false)]];
+  // error: 'allocating' and 'nonblocking' attributes are not compatible
+
+  void nb0_na1() [[clang::nonblocking(false)]] [[clang::nonallocating(true)]];
+  // Valid; the function does not allocate memory, but may lock for other reasons.
+
+  void nb0_na0() [[clang::nonblocking(false)]] [[clang::nonallocating(false)]];
+  // Valid.
+
+
+Type conversions
+----------------
+
+A performance constraint can be removed or weakened via an implicit conversion. An attempt to add
+or strengthen a performance constraint is unsafe and results in a warning.
+
+.. code-block:: c++
+
+  void unannotated();
+  void nonblocking() [[clang::nonblocking]];
+  void nonallocating() [[clang::nonallocating]];
+
+  void example()
+  {
+    // It's fine to remove a performance constraint.
+    void (*fp_plain)();
+    fp_plain = unannotated;
+    fp_plain = nonblocking;
+    fp_plain = nonallocating;
+
+    // Adding/spoofing nonblocking is unsafe.
+    void (*fp_nonblocking)() [[clang::nonblocking]];
+    fp_nonblocking = nullptr;
+    fp_nonblocking = nonblocking;
+    fp_nonblocking = unannotated;
+    // ^ warning: attribute 'nonblocking' should not be added via type conversion
+    fp_nonblocking = nonallocating;
+    // ^ warning: attribute 'nonblocking' should not be added via type conversion
+
+    // Adding/spoofing nonallocating is unsafe.
+    void (*fp_nonallocating)() [[clang::nonallocating]];
+    fp_nonallocating = nullptr;
+    fp_nonallocating = nonallocating;
+    fp_nonallocating = nonblocking; // no warning because nonblocking includes nonallocating 
+    fp_nonallocating = unannotated;
+    // ^ warning: attribute 'nonallocating' should not be added via type conversion
+  }
+
+Virtual methods
+---------------
+
+In C++, when a base class's virtual method has a performance constraint, overriding methods in
+subclasses inherit the constraint.
+
+.. code-block:: c++
+
+  struct Base {
+    virtual void unsafe();
+    virtual void safe() noexcept [[clang::nonblocking]];
+  };
+
+  struct Derived : public Base {
+    void unsafe() [[clang::nonblocking]] override;
+    // It's okay for an overridden method to be more constrained
+
+    void safe() noexcept override;
+    // This method is implicitly declared `nonblocking`, inherited from Base.
+  };
+
+Redeclarations, overloads, and name mangling
+--------------------------------------------
+
+The ``nonblocking`` and ``nonallocating`` attributes, like ``noexcept``, do not factor into
+argument-dependent lookup and overloaded functions/methods.
+
+First, consider that ``noexcept`` is integral to a function's type:
+
+.. code-block:: c++
+
+  void f1(int);
+  void f1(int) noexcept;
+  // error: exception specification in declaration does not match previous
+  //   declaration
+
+Unlike ``noexcept``, a redeclaration of `f2` with an added or stronger performance constraint is
+legal, and propagates the attribute to the previous declaration:
+
+.. code-block:: c++
+
+  int f2();
+  int f2() [[clang::nonblocking]]; // redeclaration with stronger constraint is OK.
+
+This greatly eases adoption, by making it possible to annotate functions in external libraries
+without modifying library headers.
+
+A redeclaration with a removed or weaker performance constraint produces a warning, in order to
+parallel the behavior of ``noexcept``:
----------------
Sirraide wrote:

```suggestion
A redeclaration with a removed or weaker performance constraint produces a warning, paralleling
the behavior of ``noexcept``:
```
‘in order to’ is technically wrong: we don’t warn ‘just because `noexcept` does’, but because it makes sense to warn on it ;Þ

https://github.com/llvm/llvm-project/pull/109855