[cxx-interop] Add initial documentation for strict memory safety #980

egorzhdan · 2025-05-13T15:35:11Z

99% of this document is taken from Gabor's PR: #958.

j-hui

I left a bunch of suggested changes.

Some recurring themes:

We should be consistent about referring to "[the] strict [memory] safety mode" (instead of, e.g., "strict[ly] safe mode.")
We could be more consistent about code style, e.g., writing T* x instead of T *t.

There's also no documentation about bridging for ptrcheck.h assertions.

Also, I'm wondering how much we should say, "this also works in C by the way." After all, the only C++-specific parts of this document are discussions pertaining to methods, constructors, and this, as well the stuff about std::vector and std::span at the end. I don't think we need to write this to be in C, but perhaps we should at least mention that the parts relevant to C should also work in C (i.e., without C++ interop enabled).

documentation/cxx-interop/safe-interop/index.md

j-hui · 2025-05-20T20:40:32Z

documentation/cxx-interop/safe-interop/index.md

+without any restriction. However, a small set of C++ APIs e.g. pointers/references and methods returning
+pointers will be imported as unsafe (section [Working with C++ references and view types in Swift](https://www.swift.org/documentation/cxx-interop/#working-with-c-references-and-view-types-in-swift)


punctuation nit:

Suggested change

without any restriction. However, a small set of C++ APIs e.g. pointers/references and methods returning

pointers will be imported as unsafe (section [Working with C++ references and view types in Swift](https://www.swift.org/documentation/cxx-interop/#working-with-c-references-and-view-types-in-swift)

without any restriction. However, a small set of C++ APIs—e.g., pointers/references and methods returning

pointers—will be imported as unsafe (section [Working with C++ references and view types in Swift](https://www.swift.org/documentation/cxx-interop/#working-with-c-references-and-view-types-in-swift)

This is something new to me, what do --- do?

It should have been rendered as an emdash, i.e., "—", by Markdown... but now I realize that isn't standard Markdown (though it is supported by some extensions).

I've updated the suggestion to just a unicode emdash.

documentation/cxx-interop/safe-interop/index.md

j-hui · 2025-05-21T00:11:47Z

documentation/cxx-interop/safe-interop/index.md

+C++ APIs often using standard library types or other constructs like a
+pointer and a size to represent buffers that have Swift equivalents like
+Swift's `Span` type. These Swift types have additional requirements and
+guarantees. When these properties are properly annotated on the C++ side,
+the Swift compiler can introduce safe convenience functions to make
+interacting with the C++ APIs as effortless as if they were written in Swift.


Suggested change

C++ APIs often using standard library types or other constructs like a

pointer and a size to represent buffers that have Swift equivalents like

Swift's `Span` type. These Swift types have additional requirements and

guarantees. When these properties are properly annotated on the C++ side,

the Swift compiler can introduce safe convenience functions to make

interacting with the C++ APIs as effortless as if they were written in Swift.

C++ APIs often feature parameters that denote a span of memory.

For example, some might have two parameters where one points to a memory buffer and the other designates the buffer's size;

others might use the [`std::span`](https://en.cppreference.com/w/cpp/container/span) type from the C++ standard library.

When such APIs are appropriately annotated, the Swift compiler can bridge those span-like parameters to Swift's [`Span`](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0447-span-access-shared-contiguous-storage.md) and [`MutableSpan`](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0467-MutableSpan.md) types, and the user with a safe and convenient interface to those imported APIs.

We are missing documentation for parameters annotated with __counted_by and __sized_by.

If that's only coming in a follow-up patch, then maybe we shouldn't even mention the case where we denote a span with two separate parameters, where one is a pointer and the other is a size/length.

documentation/cxx-interop/safe-interop/index.md

delcypher · 2025-05-21T22:20:35Z

documentation/cxx-interop/safe-interop/index.md

+Now the Swift compiler imports `StringRef` as a safe type and no longer
+emits a warning about using an unsafe type.
+
+### Annotating C++ APIs


There's no discussion of __counted_by, __counted_by_or_null, __sized_by, or __sized_by_or_null, or __noescape here. I feel like these should be mentioned.

delcypher · 2025-05-21T22:22:59Z

documentation/cxx-interop/safe-interop/index.md

+the Swift compiler can introduce safe convenience functions to make
+interacting with the C++ APIs as effortless as if they were written in Swift.
+
+### C++ `std::span` Support


I don't really know where to fit this in but there are no examples of using __counted_by and friends here. I realize they are not as safe as span but we are providing overloads that are safer that their original counter parts.

documentation/cxx-interop/safe-interop/index.md

delcypher · 2025-05-21T22:32:13Z

documentation/cxx-interop/safe-interop/index.md

+
+## Introduction
+
+Swift 6.2 introduces [strict memory safety mode](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0458-strict-memory-safety.md),


Aren't the safe overloads we provide completely separate from the "strict safe mode"? I've been using them without having this mode on. Introducing the interop makes it seems like it's coupled to "strict safe mode" and I don't think that's the case.

The content isn't really about strict memory safety mode. I would instead say something like this for the intro:

This document describes safe interoperability between Swift and C/C++ by using annotations to provide missing information in C/C++ types, enabling their safe use.

While optional, the strict memory safe mode introduced in Swift 6.2 can also be used to help find where these annotations should be added.

I rewrote this paragraph to make it a lot more generic.

rapidsna · 2025-06-02T14:31:35Z

documentation/cxx-interop/safe-interop/index.md

+care that the buffer they point to outlives the `StringRef` object they are encapsulated by.
+
+Swift's [non-escapable types](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0446-non-escapable.md)
+can also have lifetime dependencies, just like `StringRef`. However, the Swift compiler


This sounds a bit awkward to me because nothing talked about "StringRef" had a "lifetime dependencies".

Good point, I rephrased it slightly.

rapidsna · 2025-06-02T14:42:56Z

documentation/cxx-interop/safe-interop/index.md

+```
+
+The value returned by `fileName` will dangle after the lifetime of `normalizedPath` ends.
+We can fix this error by pushing the task of normalizing a path to the callee:


Did you mean should the "caller" of getFileName normalize the path in this example?

Rephrased this, let me know it it's better now

rapidsna · 2025-06-02T14:44:58Z

documentation/cxx-interop/safe-interop/index.md

+
+## Introduction
+
+Swift 6.2 introduces [strict memory safety mode](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0458-strict-memory-safety.md),


rapidsna · 2025-06-02T14:58:27Z

documentation/cxx-interop/safe-interop/index.md

+
+## Introduction
+
+Swift 6.2 introduces [strict memory safety mode](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0458-strict-memory-safety.md),


The content isn't really about strict memory safety mode. I would instead say something like this for the intro:

This document describes safe interoperability between Swift and C/C++ by using annotations to provide missing information in C/C++ types, enabling their safe use.

While optional, the strict memory safe mode introduced in Swift 6.2 can also be used to help find where these annotations should be added.

rapidsna · 2025-06-02T15:01:39Z

documentation/cxx-interop/safe-interop/index.md

@@ -0,0 +1,412 @@
+---
+layout: page
+title: Mixing Strict Memory Safe Swift and C++


Suggested title: "Safely mixing C, C++, and Swift" (We need a follow up to add "C" interop part).

We don't really talk about the C part at this point, so I think we can call this "Safely Mixing Swift and C++". I amended the title.

99% of this document is taken from Gabor's PR: swiftlang#958. Co-authored-by: Gabor Horvath <[email protected]> Co-authored-by: John Hui <[email protected]>

egorzhdan · 2025-06-03T14:51:41Z

Thanks folks for the feedback. Let's land this now and iterate on the C interop documentation in a separate patch.

egorzhdan · 2025-06-03T14:52:11Z

@swiftlang/website-workgroup can I ask you folks for an approval here?

alexandersandberg

Sorry for the delay!

How do website visitors find this article? There does not seem to be a link to it from other places on the website.

Does this close the other PR (#958)?

hnrklssn · 2025-06-07T05:12:55Z

How do website visitors find this article? There does not seem to be a link to it from other places on the website.

I believe we will link it from the rest of the website when it is more stable.

Does this close the other PR (#958)?

Yes.

Also, I think Egor is on vacation now, so I suggest merging it for him once you're happy with your review.

hnrklssn · 2025-06-07T05:15:03Z

documentation/cxx-interop/safe-interop/index.md

+[Swift Forums](https://forums.swift.org/c/development/c-interoperability/), or
+by filing an [issue on GitHub](https://github.com/swiftlang/swift/issues/new/choose).
+Future changes to the design or functionality of C++ interoperability will not
+break code in existing codebases [by default](#source-stability-guarantees-for-mixed-language-codebases).


Not sure if this will be added later, but I noticed that this link is dangling, just so we don't forget to write this part

egorzhdan · 2025-06-09T12:10:59Z

How do website visitors find this article? There does not seem to be a link to it from other places on the website.

Yeap, that's right! Since this document talks about a feature that's only available in a development snapshot of the compiler, not a released toolchain, I didn't link to it from the main C++ interop doc page (https://www.swift.org/documentation/cxx-interop/).

egorzhdan requested review from 0xTim, alexandersandberg, davelester, daveverwer, dempseyatgithub, federicobucchi, kaishin, shahmishal and timsneath as code owners May 13, 2025 15:35

j-hui suggested changes May 21, 2025

View reviewed changes

delcypher suggested changes May 21, 2025

View reviewed changes

egorzhdan force-pushed the egorzhdan/safe-interop-doc branch 7 times, most recently from 46ff73b to 4e8ab34 Compare May 23, 2025 13:30

j-hui mentioned this pull request May 29, 2025

Document features around safe interoperability #958

Closed

rapidsna reviewed Jun 2, 2025

View reviewed changes

egorzhdan force-pushed the egorzhdan/safe-interop-doc branch from 4e8ab34 to eb579ed Compare June 2, 2025 14:41

rapidsna reviewed Jun 2, 2025

View reviewed changes

egorzhdan force-pushed the egorzhdan/safe-interop-doc branch from eb579ed to 09c07da Compare June 2, 2025 15:23

[cxx-interop] Add initial documentation for strict memory safety

1a4b3d1

99% of this document is taken from Gabor's PR: swiftlang#958. Co-authored-by: Gabor Horvath <[email protected]> Co-authored-by: John Hui <[email protected]>

egorzhdan force-pushed the egorzhdan/safe-interop-doc branch from 09c07da to 1a4b3d1 Compare June 2, 2025 17:17

alexandersandberg reviewed Jun 5, 2025

View reviewed changes

hnrklssn reviewed Jun 7, 2025

View reviewed changes

hnrklssn mentioned this pull request Jun 7, 2025

Safe c interop #1071

Merged

egorzhdan enabled auto-merge (squash) June 9, 2025 12:24

shahmishal approved these changes Jun 9, 2025

View reviewed changes

egorzhdan merged commit 3b62155 into swiftlang:main Jun 9, 2025
3 checks passed

egorzhdan deleted the egorzhdan/safe-interop-doc branch June 9, 2025 16:28

		without any restriction. However, a small set of C++ APIs e.g. pointers/references and methods returning
		pointers will be imported as unsafe (section [Working with C++ references and view types in Swift](https://www.swift.org/documentation/cxx-interop/#working-with-c-references-and-view-types-in-swift)


		## Introduction

		Swift 6.2 introduces [strict memory safety mode](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0458-strict-memory-safety.md),

[cxx-interop] Add initial documentation for strict memory safety #980

[cxx-interop] Add initial documentation for strict memory safety #980

Uh oh!

Conversation

egorzhdan commented May 13, 2025

Uh oh!

j-hui left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

j-hui May 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rapidsna Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rapidsna Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

egorzhdan commented Jun 3, 2025

Uh oh!

egorzhdan commented Jun 3, 2025

Uh oh!

alexandersandberg left a comment

Choose a reason for hiding this comment

Uh oh!

hnrklssn commented Jun 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

egorzhdan commented Jun 9, 2025

Uh oh!

Uh oh!

Reviewers

j-hui May 20, 2025 •

edited

Loading

rapidsna Jun 2, 2025 •

edited

Loading

rapidsna Jun 2, 2025 •

edited

Loading

hnrklssn commented Jun 7, 2025 •

edited

Loading