[clang] f96ea89 - [APINotes] Document immortal reference type annotation

[via cfe-commits]

Author: Egor Zhdan
Date: 2024-11-04T11:43:20Z
New Revision: f96ea8983b8edc941107c7df2e4f08b44a1663d0

URL: https://github.com/llvm/llvm-project/commit/f96ea8983b8edc941107c7df2e4f08b44a1663d0
DIFF: https://github.com/llvm/llvm-project/commit/f96ea8983b8edc941107c7df2e4f08b44a1663d0.diff

LOG: [APINotes] Document immortal reference type annotation

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.

Added: 
    

Modified: 
    clang/docs/APINotes.rst

Removed: 
    


################################################################################
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: