[clang] [NFC] [API Notes] [Documentation] Add documentation for SwiftReturnOwnership (PR #143545)
@@ -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. Xazax-hun wrote: Would it make sense to just link to the Swift documentation that describes the default conventions? I'd prefer this to be documented only at one place so in case something changes we do not forget to update both places. 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
[clang] [NFC] [API Notes] [Documentation] Add documentation for SwiftReturnOwnership (PR #143545)
@@ -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** Xazax-hun wrote: I don't have a strong opinion here but I wonder if we need this enumeration at all. If we only said functions and objective-C methods, I think people might understand that methods (often called member functions) regardless of being static or instance functions are also included. Also this enumeration makes me thing that the restriction on the return type only applies to Objective-C and Objective-C++, and I am not sure if that is the case. 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
[clang] [NFC] [API Notes] [Documentation] Add documentation for SwiftReturnOwnership (PR #143545)
@@ -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``. Xazax-hun wrote: > using ``SwiftImportAs: reference`` Technically, is it possible that the type is annotated via attributes and not API notes? If that is the case, I think we can just drop the "using" part as it is not necessarily true. 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
[clang] [NFC] [API Notes] [Documentation] Add documentation for SwiftReturnOwnership (PR #143545)
https://github.com/fahadnayyar created https://github.com/llvm/llvm-project/pull/143545 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`. >From b4bfb1e4105b5d872aee390d0a1745e3c657dd00 Mon Sep 17 00:00:00 2001 From: Fahad Nayyar Date: Tue, 10 Jun 2025 07:51:51 -0700 Subject: [PATCH] [NFC] [API Notes] [Documentation] Add documentation for SwiftReturnOwnership --- clang/docs/APINotes.rst | 46 + 1 file changed, 46 insertions(+) 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 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [NFC] [API Notes] [Documentation] Add documentation for SwiftReturnOwnership (PR #143545)
https://github.com/egorzhdan edited 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
[clang] [NFC] [API Notes] [Documentation] Add documentation for SwiftReturnOwnership (PR #143545)
@@ -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. egorzhdan wrote: I'm not sure if this is the right place for this part of documentation, since this is really about Swift and not API Notes. But I don't have a strong opinion on this. 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
[clang] [NFC] [API Notes] [Documentation] Add documentation for SwiftReturnOwnership (PR #143545)
@@ -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** egorzhdan wrote: Minor: I'd say let's not highlight this in bold. Since we don't use bold highlighting elsewhere in this document, this would attract too much attention. 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
[clang] [NFC] [API Notes] [Documentation] Add documentation for SwiftReturnOwnership (PR #143545)
@@ -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 egorzhdan wrote: If a type is immortal, then `SwiftReturnOwnership` has no effect, right? Since Swift wouldn't do any memory management for an immortal type. 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
[clang] [NFC] [API Notes] [Documentation] Add documentation for SwiftReturnOwnership (PR #143545)
https://github.com/egorzhdan commented: Thanks, I have a few comments. 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
[clang] [NFC] [API Notes] [Documentation] Add documentation for SwiftReturnOwnership (PR #143545)
llvmbot wrote: @llvm/pr-subscribers-clang Author: None (fahadnayyar) Changes 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 `` 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
[clang] [NFC] [API Notes] [Documentation] Add documentation for SwiftReturnOwnership (PR #143545)
https://github.com/fahadnayyar ready_for_review 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
