llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT--> @llvm/pr-subscribers-clang Author: None (fahadnayyar) <details> <summary>Changes</summary> Added documentation about the usage of `SwiftReturnOwnership:` to annotate C/C++ and ObjC/C++ APIs returning C++ `SWIFT_SHARED_REFERENCE` types with `SWIFT_RETURNS_(UN)RETAINED`. --- Full diff: https://github.com/llvm/llvm-project/pull/143545.diff 1 Files Affected: - (modified) clang/docs/APINotes.rst (+46) ``````````diff diff --git a/clang/docs/APINotes.rst b/clang/docs/APINotes.rst index d20c4f9b5ba84..3b8b463ed6af7 100644 --- a/clang/docs/APINotes.rst +++ b/clang/docs/APINotes.rst @@ -195,6 +195,52 @@ declaration kind), all of which are optional: SwiftReleaseOp: immortal SwiftRetainOp: immortal +:SwiftReturnOwnership: + + Specifies the ownership convention of a function or method returning a C++ type + that has been imported as a Swift reference type using ``SwiftImportAs: reference``. + This allows Swift to correctly manage the retain and release operations at the + language boundary. + + The possible values are: + + - ``retained`` — Indicates that the function or method returns a +1 reference. + Swift will take ownership and is responsible for releasing it. + Equivalent to ``SWIFT_RETURNS_RETAINED``. + - ``unretained`` — Indicates that the function or method returns a +0 reference. + The caller must ensure the returned object remains alive. + Equivalent to ``SWIFT_RETURNS_UNRETAINED``. + + This attribute can be applied to: + + - **C++ functions** + - **C++ instance or static methods** + - **Objective-C / Objective-C++ methods or functions that return a C++ reference type** + + When omitted, the default behavior is that Swift assumes the function returns an + ```unretained``` (```+0```) reference unless the function or API has ``create`` or ``copy`` string in their name. + Use ``SwiftReturnOwnership`` to override this and + ensure proper memory management when interoperating with Swift's ARC. + + :: + + Tags: + - Name: ImmortalRefType + SwiftImportAs: reference + Methods: + - Name: methodReturningFrt__ + - Name: methodReturningFrt_returns_unretained + SwiftReturnOwnership: unretained + - Name: methodReturningFrt_returns_retained + SwiftReturnOwnership: retained + + Functions: + - Name: functionReturningFrt__ + - Name: functionReturningFrt_returns_unretained + SwiftReturnOwnership: unretained + - Name: functionReturningFrt_returns_retained + SwiftReturnOwnership: retained + :SwiftCopyable: Allows annotating a C++ class as non-copyable in Swift. Equivalent to `````````` </details> https://github.com/llvm/llvm-project/pull/143545 _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
