Safe Access to Contiguous Storage #2307

glessard · 2024-02-06T22:37:02Z

This is a proposal for safe access to borrowed memory, adding Span (formerly known as "BufferView") and RawSpan.

This proposal is a companion to (and depends on) Non-Escapable Types and on Lifetime Dependency Annotations for Non-escapable Types.

proposals/nnnn-safe-shared-contiguous-storage.md

Co-authored-by: Alex Martini <[email protected]>

proposals/nnnn-safe-shared-contiguous-storage.md

- this is redundant, since it is the same as `String.UTF8View`

proposals/nnnn-safe-shared-contiguous-storage.md

DougGregor · 2024-08-19T17:51:36Z

proposals/nnnn-safe-shared-contiguous-storage.md

+
+```swift
+extension Span where Element: ~Copyable & ~Escapable {
+ func withUnsafeBufferPointer<E: Error, Result: ~Copyable & ~Escapable>(


I don't think Result can be ~Escapable here without the lifetimes proposal.

I have a meta-question about the design here. Span is already non-escaping itself, and these operations that produce an unsafe buffer pointer obviously have to break that requirement. Given that, it doesn't feel like using the closure here is providing extra safety over (e.g.) a property that produces the UnsafeBufferPointer, but it's a lot less ergonomic. Could we consider instead to have:

var unsafeBufferPointer: UnsafeBufferPointer<Element> { get }

Span.withUnsafeBufferPointer ensures that the Span's lifetime, and whatever that span depends on, extend across all valid uses of the pointer. The rules for pointer validity in closure taking methods are clear. There's nothing new here. As long as programmers follow the usual rules, they can't introduce any new form of unsafety.
The compiler should be able to diagnose pointer escapes from the closure, but that's a separate discussion!

DougGregor · 2024-08-19T17:52:15Z

proposals/nnnn-safe-shared-contiguous-storage.md

+ func withUnsafeBytes<E: Error, Result: ~Copyable & ~Escapable>(
+ _ body: (_ buffer: UnsafeRawBufferPointer) throws(E) -> Result
+ ) throws(E) -> Result
+}
+
+extension RawSpan {
+ func withUnsafeBytes<E: Error, Result: ~Copyable & ~Escapable>(
+ _ body: (_ buffer: UnsafeRawBufferPointer) throws(E) -> Result
+ ) throws(E) -> Result
+}


Same suggestion about having a property here:

var unsafeTypes: UnsafeRawBufferPointer { get }

DougGregor · 2024-08-19T17:54:07Z

proposals/nnnn-safe-shared-contiguous-storage.md

+}
+```
+
+##### Accessing subranges of elements:


As I noted earlier on, all of the extracting functions depend on lifetime dependencies. Perhaps provide a closure-based withSubspan?

DougGregor · 2024-08-19T17:55:59Z

proposals/nnnn-safe-shared-contiguous-storage.md

+ /// - Parameters:
+ /// - type: The type as which to view the bytes of this span.
+ /// - Returns: A typed span viewing these bytes as instances of `T`.
+ public func unsafeView<T: BitwiseCopyable>(as type: T.Type) -> Span<T>


IIUC, this requires lifetime dependencies. Change it to a closure-taking withUnsafeView?

DougGregor · 2024-08-19T17:56:14Z

proposals/nnnn-safe-shared-contiguous-storage.md

+ /// The closure's parameter is valid only for the duration of
+ /// its execution.
+ /// - Returns: The return value of the `body` closure parameter.
+ func withUnsafeBytes<E: Error, Result: ~Copyable & ~Escapable>(


As noted earlier, can this be a property?

DougGregor · 2024-08-19T17:56:36Z

proposals/nnnn-safe-shared-contiguous-storage.md

+```swift
+extension RawSpan {
+
+ public func extracting(_ bounds: Range<Int>) -> Self


Same issue as earlier; this is based on lifetime dependencies.

DougGregor · 2024-08-19T17:58:23Z

proposals/nnnn-safe-shared-contiguous-storage.md

+
+Some types store their internal representation in a piecewise-contiguous manner, such as trees and ropes. Some operations naturally return information in a piecewise-contiguous manner, such as network operations. These could supply results by iterating through a list of contiguous chunks of memory.
+
+#### <a name="MutableSpan"></a>Safe mutations of memory with `MutableSpan<T>`


Looking forward to this proposal! ;)

stephentyrone · 2024-09-06T01:47:49Z

proposals/nnnn-span-access-shared-contiguous-storage.md

- public func extracting(droppingFirst k: Int) -> Self
+ /// - Parameters:
+ /// - indices: a range of indices to validate
+ public func boundsPrecondition(_ indices: Range<Int>)


span.boundsPrecondition(range) is just precondition(span.boundsContain(range)), right? Do we really need/want sugar for this?

Re: naming, I think things get somewhat easier if we drop the precondition func, then we just have boundsContain, whose naming isn't great because it's kind of oblique. The question we're really asking is "are the indices in this range valid for this span?". Something like span.indicesContain(range), though that then raises the question of "why isn't this just span.indices.contains(range)?" (probably performance?)

If we have these, do we also need ClosedRange versions?

Yes, boundsPrecondition's implementation is precondition(boundsContain(range)). There's maybe an argument to be made that the sugar hurts here, since it doesn't capture the correct line of code in the defaulted arguments of precondition().

I haven't needed the ClosedRange versions because the RangeExpression-taking functions end up forwarding to the usual Range-taking functions. Maybe we would want them. We could take out the sugared preconditions and add ClosedRange bounds-checking functions.

DougGregor

This is looking great to me, thank you

DougGregor · 2024-09-06T16:09:20Z

proposals/nnnn-span-access-shared-contiguous-storage.md

- public func extracting(droppingFirst k: Int) -> Self
+ /// - Parameters:
+ /// - indices: a range of indices to validate
+ public func boundsPrecondition(_ indices: Range<Int>)


If we have these, do we also need ClosedRange versions?

DougGregor · 2024-09-06T16:16:33Z

proposals/nnnn-span-access-shared-contiguous-storage.md

+ public func withSpan<E: Error, Result: ~Copyable>(
+ _ body: (_ elements: Span<Element>) throws(E) -> Result
+ ) throws(E) -> Result


I'm one of those people who would like this API :)

The complex semantics of this makes it undesirable, as exhibited by the overcomplicated signature. What we actually need is a storage property that directly returns a Span, tied to the lifetime of self.

atrick · 2024-09-06T23:49:22Z

proposals/nnnn-span-access-shared-contiguous-storage.md

+```swift
+@frozen
+public struct Span<Element: ~Copyable & ~Escapable>: Copyable, ~Escapable {
+ internal var _start: UnsafePointer<Element>


Span has the wrong pointer type: UnsafePointer<Element>. The underlying pointer should be UnsafeRawPointer. An important goal of Span is that it can be used to reinterpret memory as different BitwiseCopyable elements. It needs to be possible to convert Span<T: BitwiseCopyable> to Span<U: BitwiseCopyable>. That should require an explicit unsafe API but should still be well-defined. If you do this conversion with an underlying typed pointer, you get undefined behavior. We want multiple read-only spans to safely view the same underlying memory as different types. We also want to be able to view slices of a RawSpan as a particular element type. This is the same problem. Note that RawSpan does not provide any additional functionality; it is only a convenience for buffers of heterogenous elements, where declaring an element type might be misleading at the API level.

We do not want to describe strict aliasing rules and undefined behavior in the Span API!

Hm; unrelated to the above: didn't we intend to use buffer-pointer layout for this? The start pointer ought to be optional.

I've updated this to be optional, with an explanation (hadn't noticed that a push failed on Friday.) We won't use buffer-pointer layout after all, because we do want the pointer to be raw.

atrick · 2024-09-07T00:09:01Z

proposals/nnnn-span-access-shared-contiguous-storage.md

+extension RawSpan {
+ public init<T: BitwiseCopyable>(_ span: Span<T>)
+
+ public func unsafeView<T: BitwiseCopyable>(as type: T.Type) -> Span<T>


Since you're mentioning RawSpan.unsafeView<T: BitwiseCopyable>(as type: T.Type) -> Span<T> here, we may also want to explain that this is a safe API as long as the memory contains a value bit pattern for T at each position. Span<T> does not impose any strict aliasing demands on the programmer; they can use multiple read-only spans to safely view the same underlying memory as different types.

atrick · 2024-09-07T00:23:29Z

proposals/nnnn-span-access-shared-contiguous-storage.md

+ public var count: Int { get }
+ public var isEmpty: Bool { get }
+
+ public subscript(_ position: Int) -> Element { _read }


public subscript(_ position: Int) -> Element { _read }

This is not, in fact, the API that we want long term; it won't be compatible with lifetime-dependent values that are derived from the span.

We really want some new spelling for ~Copyable projections, like:

public subscript(_ position: Int) -> Element { borrow }

For now, we could say:

public subscript(_ position: Int) -> Element { unsafeAddress }

Either way, we end up with an extra mangling for this API that may become vestigial in the future. But with unsafeAddress, at least we have the full functionality of some future, safe "borrow accessor".

@jckarter what do you think?

The future directions attempts to explain that the _read accessor is a placeholder. I expect the implementation of such placeholders to be non-ABI until there is a final spelling. I could add a reference to the future directions item after this.

Ok. I realize the plan is to initially implement Span.subscript via _read. I'll just point out that it will limit usability. unsafeAddress will at least support the same use cases that a borrow accessor would support.

- add `boundsContain(_ bounds: ClosedRange<Int>)`

lorentey · 2024-09-09T16:54:14Z

proposals/nnnn-span-access-shared-contiguous-storage.md

+```swift
+@frozen
+public struct Span<Element: ~Copyable & ~Escapable>: Copyable, ~Escapable {
+ internal var _start: UnsafePointer<Element>


Hm; unrelated to the above: didn't we intend to use buffer-pointer layout for this? The start pointer ought to be optional.

proposals/nnnn-span-access-shared-contiguous-storage.md

lorentey · 2024-09-09T16:57:54Z

proposals/nnnn-span-access-shared-contiguous-storage.md

+ /// - Parameters:
+ /// - index: an index to validate
+ /// - Returns: true if `index` is a valid index
+ public func boundsContain(_ index: Int) -> Bool


This name needs to be reconsidered. isValidIndex(_:)

proposals/nnnn-span-access-shared-contiguous-storage.md

lorentey · 2024-09-09T17:02:23Z

proposals/nnnn-span-access-shared-contiguous-storage.md

+ /// Parameters:
+ /// - span: a span of the same type as `self`
+ /// Returns: whether `span` is a subrange of `self`
+ public func contains(_ span: borrowing Self) -> Bool


Unfortunately, we have blown the contains name to mean elementwise containment, not structural containment. This usage is not compatible with that, so we need to use a different name for it.

isSuperspan(of:)? isSubspan(of:)? isWider(than:)? 😕

[Notes from in person discussions]

span.isWithin(other) appears to be a workable spelling for this.

We also need to have an isIdentical(to:) method, to check equivalence. (a.isIdentical(to: b) == a.isWithin(b) && b.isWithin(a), but we wouldn't want to spell/implement it that way.)

If the elements are bitwise copyable, then this operation needs to check alignment, which is a surprising complication, explaining why we'd want to ship this functionality in the stdlib. (This also needs to be called out within the docs.)

This may also turn into a solid argument against using the isWithin name, especially when considering the equivalent APIs on Range in point 5 below. (If so, perhaps something like isSubspan is the way to go.)

We should add equivalent members to the UnsafeBufferPointer types, to keep the stdlib coherent with itself, and to resolve some long standing omissions of basic functionality.

extension Unsafe[Mutable]BufferPointer { func isIdentical(to other: UnsafeBufferPointer<Element>) -> Bool func isIdentical(to other: UnsafeMutableBufferPointer<Element>) -> Bool func isWithin(_ other: UnsafeBufferPointer<Element>) -> Bool func isWithin(_ other: UnsafeMutableBufferPointer<Element>) -> Bool }

isWithin ought to also be added to the range types:

extension Range { func isWithin(other: Range) -> Bool func isWithin(other: ClosedRange) -> Bool } extension ClosedRange { func isWithin(other: Range) -> Bool func isWithin(other: ClosedRange) -> Bool }

(These types already provide the functionality of isIdentical in their == operation.)

The notion of unaligned bounds makes this somewhat dangerous -- Range<UnsafePointer<T>>.isWithin(_:) would sometimes return different results than an isWithin call on UnsafeBufferPointer or Span values over the same region of memory.

The preexisting [Closed]Range.overlaps hints at a need to provide [Raw]Span.overlaps and Unsafe[Mutable][Raw]BufferPointer.overlaps operations. (As well as intersect and union/merge/combine operations.) This does not seem to be an urgent need though.

lorentey · 2024-09-09T17:10:16Z

proposals/nnnn-span-access-shared-contiguous-storage.md

+ /// This is an unsafe operation. Failure to meet the preconditions
+ /// above may produce an invalid value of `T`.


When the address has incorrect alignment, are we really going to return an invalid value? (Rather than, say, sometimes causing a fault?)

There exist systems where a load instruction simply masks off the low bits and always loads whatever it finds at the resulting aligned address (AltiVec loads behave this way on PPC, for example).

Unaligned loads can fault in embedded world as well, especially when targeting memory that isn't DRAM. In a sense, the worst outcome isn't necessarily an invalid value of T.

The point of this is that there is no trap other than bounds checking, and the T instance's memory could be in a state that does not respect T's invariants.

proposals/nnnn-span-access-shared-contiguous-storage.md

lorentey · 2024-09-09T17:14:35Z

proposals/nnnn-span-access-shared-contiguous-storage.md

+ public func contains(_ span: borrowing Self) -> Bool
+
+ public func offsets(of span: borrowing Self) -> Range<Int>


Same problems as with Span -- contains implements the wrong semantics for that name, and offsets(of:) has an awkward name/shape.

public func isWithin(_ other: borrowing Self) -> Bool // Perhaps removed public func byteOffsets(of subspan: borrowing Self) -> Range<Int>?

lorentey · 2024-09-09T17:25:06Z

proposals/nnnn-span-access-shared-contiguous-storage.md

+ public func withSpan<E: Error, Result: ~Copyable>(
+ _ body: (_ elements: Span<Element>) throws(E) -> Result
+ ) throws(E) -> Result


The complex semantics of this makes it undesirable, as exhibited by the overcomplicated signature. What we actually need is a storage property that directly returns a Span, tied to the lifetime of self.

lorentey · 2024-09-09T21:37:41Z

proposals/nnnn-span-access-shared-contiguous-storage.md

+
+```swift
+@frozen
+public struct Span<Element: ~Copyable & ~Escapable>: Copyable, ~Escapable {


Why are we proposing Span with support for nonescapable elements?

glessard added 6 commits February 6, 2024 14:19

[draft proposal] Safe Access to Contiguous Storage

8093cad

edit placeholder proposal url

548b250

link to pitch thread

7cfd46d

declare typealiases correctly

9993694

add “first” and “last” properties

fece228

fix inits from raw pointers

a3784fe

amartini51 reviewed Feb 13, 2024

View reviewed changes

proposals/nnnn-safe-shared-contiguous-storage.md Outdated Show resolved Hide resolved

glessard and others added 6 commits February 13, 2024 16:17

Update proposals/nnnn-safe-shared-contiguous-storage.md

ceb261d

Co-authored-by: Alex Martini <[email protected]>

add view(as: T)

2480ca2

incorporate feedback from pitch discussion

441a5c8

enclose index and iterator types in the main type

b360a50

update protocol declaration

9aa96ea

link to additional related pitches

1adba6d

rjmccall added workgroup: blocked This proposal is blocked on some other consideration LSG Contains topics under the domain of the Language Steering Group labels Apr 1, 2024

glessard and others added 7 commits April 15, 2024 17:48

fix a stored property type

300591d

rename type, adopt new syntax

ed5fea2

various updates

7b2bb1f

add more RawSpan API, doc-comment fixes

f876043

Added more prose, added TODOs for further clarification

844e661

Update proposals/nnnn-safe-shared-contiguous-storage.md

15de4ab

remove some trailing whitespace from code blocks

be180f1

atrick self-requested a review April 26, 2024 04:28

milseman and others added 3 commits May 9, 2024 10:27

Update

26a7637

Update

50a38df

lots of updates

6add19b

milseman reviewed Jun 20, 2024

View reviewed changes

lorentey reviewed Jun 20, 2024

View reviewed changes

proposals/nnnn-safe-shared-contiguous-storage.md Outdated Show resolved Hide resolved

lorentey reviewed Jun 20, 2024

View reviewed changes

proposals/nnnn-safe-shared-contiguous-storage.md Outdated Show resolved Hide resolved

glessard commented Jun 20, 2024

View reviewed changes

proposals/nnnn-safe-shared-contiguous-storage.md Outdated Show resolved Hide resolved

al45tair reviewed Jul 29, 2024

View reviewed changes

proposals/nnnn-safe-shared-contiguous-storage.md Outdated Show resolved Hide resolved

glessard added 3 commits August 14, 2024 11:43

remove extension to Character.UTF8View

4496c54

- this is redundant, since it is the same as `String.UTF8View`

add closure-taking api, move initializers to future

66a78f8

shrink byte-parsing helpers future direction

32adc87

DougGregor reviewed Aug 19, 2024

View reviewed changes

glessard added 9 commits September 5, 2024 09:39

formatting, text moved around

3d45c07

rename file to include the word “span”

54912a7

improve title

8a26a9d

add link to preview implementation

c7e464a

lots of changes

9f32a16

remove UBP.withUnsafeSpan and similar

979f5bb

remove another ~Escapable that cannot be promised

0235837

add a missing blurb

d656ead

improve name of bounds-checking functions

13f30ce

stephentyrone reviewed Sep 6, 2024

View reviewed changes

DougGregor approved these changes Sep 6, 2024

View reviewed changes

addition about closure-based unsafe escape-hatch functions

b7e1933

atrick reviewed Sep 6, 2024

View reviewed changes

atrick reviewed Sep 7, 2024

View reviewed changes

remove boundsPrecondition, add boundsContain overload

2255c15

- add `boundsContain(_ bounds: ClosedRange<Int>)`

lorentey reviewed Sep 9, 2024

View reviewed changes

glessard and others added 7 commits September 9, 2024 14:43

start pointer clarification

92b2e2f

improve coroutine explanation

3b12717

convert non-breaking spaces

38c6840

fix extensions

1279d70

[feedback] mention initializers earlier

e18eafe

rename span comparison functions

b9a166e

fix span comparison signatures and documentation

25aca7e

DougGregor merged commit be7789f into swiftlang:main Sep 18, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Safe Access to Contiguous Storage #2307

Safe Access to Contiguous Storage #2307

glessard commented Feb 6, 2024 •

edited

Loading

DougGregor Aug 19, 2024

atrick Aug 21, 2024

DougGregor Aug 19, 2024

DougGregor Aug 19, 2024

DougGregor Aug 19, 2024

DougGregor Aug 19, 2024

DougGregor Aug 19, 2024

DougGregor Aug 19, 2024

stephentyrone Sep 6, 2024

DougGregor Sep 6, 2024

glessard Sep 7, 2024

DougGregor left a comment

DougGregor Sep 6, 2024

DougGregor Sep 6, 2024

lorentey Sep 9, 2024

atrick Sep 6, 2024

lorentey Sep 9, 2024

glessard Sep 9, 2024

atrick Sep 7, 2024

atrick Sep 7, 2024

glessard Sep 7, 2024

atrick Sep 9, 2024

lorentey Sep 9, 2024

lorentey Sep 9, 2024

lorentey Sep 9, 2024

lorentey Sep 11, 2024

lorentey Sep 9, 2024

stephentyrone Sep 10, 2024

apple-fcloutier Sep 10, 2024

glessard Sep 10, 2024

lorentey Sep 9, 2024

lorentey Sep 11, 2024 •

edited

Loading

lorentey Sep 9, 2024

lorentey Sep 9, 2024


		Some types store their internal representation in a piecewise-contiguous manner, such as trees and ropes. Some operations naturally return information in a piecewise-contiguous manner, such as network operations. These could supply results by iterating through a list of contiguous chunks of memory.

		#### <a name="MutableSpan"></a>Safe mutations of memory with `MutableSpan<T>`

		/// This is an unsafe operation. Failure to meet the preconditions
		/// above may produce an invalid value of `T`.

		public func contains(_ span: borrowing Self) -> Bool

		public func offsets(of span: borrowing Self) -> Range<Int>

Safe Access to Contiguous Storage #2307

Safe Access to Contiguous Storage #2307

Conversation

glessard commented Feb 6, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DougGregor left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lorentey Sep 11, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

glessard commented Feb 6, 2024 •

edited

Loading

lorentey Sep 11, 2024 •

edited

Loading