[clang] [APINotes] Document immortal reference type annotation (PR #114042)

[via cfe-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-clang

Author: Egor Zhdan (egorzhdan)

<details>
<summary>Changes</summary>

API Notes allow annotating a C++ reference type with its retain/release operations. These are honored by the Swift compiler when the type is used from Swift. Apart from names of C++ functions that need to be called to retain/release the object, API Notes also accept a value of `immortal` which indicates that the object is to be considered alive for the duration of the program.

---
Full diff: https://github.com/llvm/llvm-project/pull/114042.diff


1 Files Affected:

- (modified) clang/docs/APINotes.rst (+18) 


``````````diff
diff --git a/clang/docs/APINotes.rst b/clang/docs/APINotes.rst
index dcefa6810dac67..d20c4f9b5ba843 100644
--- a/clang/docs/APINotes.rst
+++ b/clang/docs/APINotes.rst
@@ -169,6 +169,20 @@ declaration kind), all of which are optional:
   to ``SWIFT_RETURNS_INDEPENDENT_VALUE``) or ``computed_property`` (equivalent to
   ``SWIFT_COMPUTED_PROPERTY``).
 
+  ::
+
+    Tags:
+    - Name: OwnedStorage
+      SwiftImportAs: owned
+
+:SwiftRetainOp, SwiftReleaseOp:
+
+  Controls the lifetime operations of a class which uses custom reference
+  counting. The class must be annotated as a reference type using
+  ``SwiftImportAs: reference``. The values are either names of global functions,
+  each taking a single parameter of a pointer type, or ``immortal`` for a type
+  that is considered alive for the duration of the program.
+
   ::
 
     Tags:
@@ -176,6 +190,10 @@ declaration kind), all of which are optional:
       SwiftImportAs: reference
       SwiftReleaseOp: RCRelease
       SwiftRetainOp: RCRetain
+    - Name: ImmortalSingleton
+      SwiftImportAs: reference
+      SwiftReleaseOp: immortal
+      SwiftRetainOp: immortal
 
 :SwiftCopyable:
 

``````````

</details>


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