Skip to content

[cxx-interop] Add SWIFT_RETUNRS_(UN)RETAINED discussions to C++ interop docs #1077

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[cxx-interop] Add SWIFT_RETUNRS_(UN)RETAINED discussions to C++ interop docs #1077

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions documentation/cxx-interop/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1255,6 +1255,30 @@ object.doSomething()
// `object` will be released here.
```

To specify the ownership of returned `SWIFT_SHARED_REFERENCE` types, use the `SWIFT_RETURNS_RETAINED` and `SWIFT_RETURNS_UNRETAINED` annotations on C++ functions and methods. These annotations tell the Swift compiler whether the type is returned as `+1` (retained) or `+0` (unretained). This is necessary to ensure that appropriate `retain`/`release` operations are inserted at the boundary:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would these annotations work on C, and Objective-C code? If yes, maybe we should not emphasize C++ here (also this is the C++ interop documentation so this might be redundant information anyway.)


```c++
// Returns +1 ownership; Swift will take responsibility for releasing it.
SharedObject* makeOwnedObject() SWIFT_RETURNS_RETAINED;

// Returns +0 ownership; the caller must ensure the object stays alive.
SharedObject* makeUnownedObject() SWIFT_RETURNS_UNRETAINED;
```

These ownership conventions are reflected naturally in Swift:
```swift
let owned = makeOwnedObject()
owned.doSomething()
// `owned` is automatically released when it goes out of scope

let unowned = makeUnownedObject()
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor: looks like the syntax highlighter treats unowned as a keyword here, could we pick a different name to avoid the confusion on reader's side?

unowned.doSomething()
// make sure `unowned` remains valid while in use
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wouldn't Swift automatically increase reference counting operations to guarantee that unowned is valid? I think we should check with someone if we are unsure before adding this to the documentation.

```

These ownership annotations are also supported in Objective-C or Objective-C++ functions that return C++ `SWIFT_SHARED_REFERENCE` types.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it possible for an Objective-C function to return a C++ type? Isn't that already Objective-C++?



Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the default ownership convention documented somewhere? If not, this might be a good place to add.

### Inheritance and Virtual Member Functions

Similar to value types, casting an instance of a derived reference type to a
Expand Down