Skip to content

[cxx-interop] Add documentation about calling ctor or static factory of SWIFT_SHARED_REFERENCE types as Swift Initializer #1079

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 documentation about calling ctor or static factory of SWIFT_SHARED_REFERENCE types as Swift Initializer #1079

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
12 changes: 10 additions & 2 deletions documentation/cxx-interop/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1239,8 +1239,8 @@ To specify that a C++ type is a shared reference type, use the `SWIFT_SHARED_REF
class SharedObject : IntrusiveReferenceCounted<SharedObject> {
public:
SharedObject(const SharedObject &) = delete; // non-copyable
SharedObject(); // Constructor
Copy link
Contributor

Choose a reason for hiding this comment

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

I think the readers of this document already know that this is a constructor, they probably know basic C++, we don't need this comment.


static SharedObject* create();
void doSomething();
} SWIFT_SHARED_REFERENCE(retainSharedObject, releaseSharedObject);

Expand All @@ -1250,11 +1250,19 @@ void releaseSharedObject(SharedObject *);

Now that `SharedObject` is imported as a reference type in Swift, the programmer will be able to use it in the following manner:
```swift
let object = SharedObject.create()
// Call the C++ constructor of SharedObject using Swift initializer syntax.
Copy link
Contributor

Choose a reason for hiding this comment

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

I'd rather have a comment like: The C++ constructor is imported as a Swift initializer. The users can figure out this is an initializer syntax on their own if they know some swift.

let object = SharedObject()
Copy link
Contributor

Choose a reason for hiding this comment

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

I would keep both the create and the initializer example as the static factory method still can express certain things we cannot do using constructors, for example using a custom allocator and taking extra parameters for that allocator.

object.doSomething()
// `object` will be released here.
```

You can create instances of `SharedObject` directly in Swift by calling its C++ constructor through a Swift initializer.

Alternatively, you can construct instances using a user-defined static factory function, provided that the factory function is annotated with `SWIFT_NAME("init(...)")`, where the number of `_` placeholders matches the number of parameters in the factory function
Copy link
Contributor

Choose a reason for hiding this comment

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

We should have a code example for this SWIFT_NAME trick. Also we should explain why would the user want to do this (e.g., we don't support custom allocators).

I think it is worth mentioning that we use the default new/delete for allocation/deallocation and if someone wants to disable the importing of ctors as initializers they can delete these operations for their class.


> **Note**: If a C++ constructor and a user-annotated static factory (via `SWIFT_NAME`) have identical parameter signatures, Swift prefers the static factory when resolving initializer calls.


### Inheritance and Virtual Member Functions

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