[cxx-interop] Document guarantees and assumptions for non-const C++ s… #816
Conversation
…hared references passed to a C++ API from Swift
fahadnayyar
requested review from
0xTim,
alexandersandberg,
daveverwer,
dempseyatgithub,
parispittman,
kaishin,
shahmishal,
timsneath and
federicobucchi
as code owners
|
@swift-ci test |
| @@ -1271,6 +1271,20 @@ owned/guaranteed calling conventions. The C++ callers must guarantee that `x` is | |||
| Note that functions returning a shared reference type such as `returnSharedObject` transfer the ownership to the caller. | |||
| The C++ caller of this function is responsible for releasing the object. | |||
|
|
|||
| If a C++ Shared Reference Type is passed as an argument to a C++ API from Swift, the Swift compiler *guarantees* that the passed value would be alive. Also Swift *assumes* that the C++ API is not consuming i.e., it returns with a valid object in the passed reference at the end of the C++ API call. | |||
There was a problem hiding this comment.
@fahadnayyar I would like to suggest these changes:
f a C++ Shared Reference Type is passed as an argument to a C++ API from Swift, the Swift compiler guarantees that the passed value would be alive.
Can we add the following after this sentence.
... guarantees that the passed value would be alive, and retains ownership of the value. In other words, the argument is passed as +0 and there is no transfer of ownership.
Also Swift assumes that the C++ API is not consuming i.e., it returns with a valid object in the passed reference at the end of the C++ API call.
Can we rephrase this as follows:
The C++ function is responsible for ensuring that the value pointed to by the parameter is alive during and at the end of the call. The C++ function should not assume it has ownership of the value and should do necessary retain operations if it is needs to take ownership.
If the argument is an inout (non-const reference) as shown below:
void takeSharedObjectAsInout(SharedObject *& x) { ... }which would be imported in Swift as
func takeSharedObjectAsInout(_ x: inout SharedObject) { ... }If the C++ function overwrites the value of the argument with the new value, it is responsible for releasing the old value, and ensuring that the new value is properly retained so that the Swift caller has ownership of the new value when the function returns. Adhering to these rules is necessary to safely and correctly pass around SWIFT_SHARED_REFERENCE between Swift and C++. These rules are also generally recommended conventions to manage shared objects that use reference counting.
| @@ -1271,6 +1271,20 @@ owned/guaranteed calling conventions. The C++ callers must guarantee that `x` is | |||
| Note that functions returning a shared reference type such as `returnSharedObject` transfer the ownership to the caller. | |||
| The C++ caller of this function is responsible for releasing the object. | |||
|
|
|||
| If a C++ Shared Reference Type is passed as an argument to a C++ API from Swift, the Swift compiler *guarantees* that the passed value would be alive. Also Swift *assumes* that the C++ API is not consuming i.e., it returns with a valid object in the passed reference at the end of the C++ API call. | |||
There was a problem hiding this comment.
I have a few comments on the wording and formatting:
- The rest of this document doesn't capitalize "C++ reference types", I think it's better to be consistent here.
- I think it's better not to use bold highlighting for
*guarantees*/*assumes*, the rest of the document doesn't use it, and I feel that it attracts too much attention. - Minor: the comma
,usually goes beforei.e., could you please swap them? - I don't have a strong opinion, but to me "function call" sounds better than "API call", since to me API means a collection of functions, types, etc.
|
|
||
| ```swift | ||
| var obj = SharedObject.create() | ||
| receiveSharedObject(obj) // Swift gaurantees that obj is alive |
| receiveSharedObject(obj) // Swift gaurantees that obj is alive | ||
| ``` | ||
|
|
||
| ```c++ |
There was a problem hiding this comment.
Thanks for explicitly specifying the language for code blocks! 👍
|
@egorzhdan @fahadnayyar Is this PR ready to be merged? |
|
@shahmishal no, not yet. |
These assumptions and guarantees are important to be documented to make sure that when C++ Shared Reference Types are passed as a non-const parameter to a C++ function or method from swift, then user's don't make wrong assumptions about the default behaviour supported in the Swift compiler.