[Pitch] Safe Access to Contiguous Storage

glessard · 2024-02-09T20:17:53.627Z

dmt:

Why is there a mix of functions that work with Index and byte offsets?

One of the things we would like to avoid with StorageView is to have an explicitly-untyped version. This is why the load and loadUnaligned functions are restricted to those StorageViews that contain BitwiseCopyabletypes. (BitwiseCopyable will soon be proposed, but simply it's a type that does not require deinitialization, explicitly or implicitly).

I have not added type-reinterpreting functions on whole views, but we should add them. What is uncertain to me are the restrictions on the second type; should both types be required to be BitwiseCopyable? Note it's unclear whether the aligned load() function should have that restriction; it does not on RawPointer.

This being said the existing load and loadUnaligned functions on UnsafeRawPointer and UnsafeRawBufferPointer use byte offsets exclusively, not indices. I hope that we can soon try a full prototype of StorageView with a parser, and ascertain whether either the offset approach or the index approach for load is unnecessary.

It is an interesting question whether we should restrict load and loadUnaligned to StorageView<UInt8>. If we did so, should we also add them to StorageView<Int8>? Why not on StorageView<Int16>? The answer I find most natural is to not restrict their availability unduly. They do not make sense over a view to a non-BitwiseCopyable type such as AnyObject, but is there a reason not to allow them if your viewed type is (Int, SIMD8<Int32>)?

za_creature · 2024-02-09T20:42:11.196Z

The key safety feature is that a StorageView cannot escape to a scope where the value it borrowed no longer exists.

This is the way!

Does this also hold true for non-escapable async?

glessard · 2024-02-09T21:37:28.122Z

Sendability and Escapability are complementary, along different axes. A non-escapable value could be passed via a borrowed parameter of a function that's in another isolation domain, but once there the non-escapability would mean that the value can't be copied for safekeeping into e.g. the storage of that function's actor.
(I'm not certain I answered the question you meant to ask, though.)

za_creature · 2024-02-09T21:57:57.709Z

I think you did

I was concerned about async functions being conceptually @escaping and whether I would be able to do (apologies for not following the actual proposed API syntax):

await sock.send(buffer.view[0..<512])

But based on your answer (and ignoring Sendable), I guess that ~Escapable is a conceptual superset of ~Copyable?

glessard · 2024-02-09T22:04:36.343Z

Escapability limits where a value can go. Noncopyability ensures there is only one copy, but a noncopyable value could be moved anywhere. This is why a MutableStorageView would need to be both non-copyable and non-escapable. The non-escapability ensures temporal soundness (that is accesses happen only while the memory allocation is known to be valid), while the non-copyability ensures against data races by enforcing exclusivity.

za_creature · 2024-02-09T22:39:07.541Z

glessard:

temporal soundness (that is accesses only while the allocation is valid)

That's the pitch, but how does it work in practice?

await marks a (possibly long) suspension point, usually modeled as two calls with store respectively restore. This is semantically non-escaping but any call after await is really naturally @escaping. I guess that the compiler can take care of that since it's ~~turtles~~ Tasks all the way down.

I think that my confusion was about @escaping fn vs ~Escapable struct

Approaching the problem from a different angle (re: atomics, continuations, int a[n]), it feels like ~Escapable is both a solution and a nice pun. Since there's already some bikeshedding about the name, could you @glessard come up with a few ~~non-temporal~~* use cases where non-escapable is usefully less strict than at-fixed-memory-address?

I would definitely love to see consuming / borrowing semantics being completely orthogonal to escaping semantics

*: EDIT too many double-negations

Karl · 2024-02-11T18:38:06.970Z

I'm also not thrilled about the name "storage view". I think that name has connotations which are not always accurate - developers may wish to expose lexically-scoped buffers in their APIs for a variety of reasons.

For instance, perhaps I want to stream the bytes of a file, giving a closure temporary access to a stack-allocated buffer:

struct File {
  func stream(_ processBytes: (StorageView<UInt8>) -> Void)
}

And I've mentioned previously that if we had generator functions in the language, one could even imagine an async iterator using this pattern.

[Pitch] Generalize `AsyncSequence` and `AsyncIteratorProtocol`

And then you'd write your iterator like so:
mutating func next<T>(
  _ yield: ([UInt8]) async throws(T) -> IterationResult
) async throws(errorUnion(Failure, T)) {

  var buffer = [UInt8]()
  while await populateBuffer(&buffer) {
    guard try await yield(buffer) == .continue else { break }
  }
}
And now that we're yielding borrows of the element rather than returning copies of it, the element can instead be a non-copyable type -- and even a non-escaping type like some kind of stack buffer.

And so if we imagine some kind of File.ChunkedBytesGenerator (or whatever you want to call it), its associated Element type would be called StorageView. But those values don't represent the storage of the file or the bytes generator. It's not really storage of anything that you'd care about; it's just a non-escapable buffer.

I also think the name is unnecessarily scary/low-level. If this is a safe type, we should give it a nicer name. I think the term "array" is friendlier for Swift developers than "buffer", so I'd suggest something along the lines of SharedArray, NonOwnedArray (or maybe even "unowned"), or BorrowedArray.

I have more to say about this (in particular the idea of a ContiguousStorage protocol - I don't love it), but for now I wanted to mention something about the name.

glessard · 2024-02-12T19:40:03.540Z

I do think that the term "Borrowed" gets to the essence of the type. Personally I don't think we should overload the term "Array" too much. Is it a BorrowedContiguousMemorySpan? a BorrowedBuffer? just BorrowedMemory?

Jumhyn · 2024-02-12T20:12:46.660Z

glessard:

Is it a BorrowedContiguousMemorySpan? a BorrowedBuffer?

The former here feels quite wordy to me and I feel like UnsafeBufferPointer provides good precedent for 'buffer' as a simpler way to refer to this. So BorrowedBuffer SGTM.

bbrk24 · 2024-02-13T03:43:18.983Z

Jumhyn:

feels quite wordy to me

still better than the full name of, say, UMRBP.

lorentey · 2024-02-13T03:57:48.616Z

Very nice!

Minor notes follow below.

In the ContiguousStorage protocol, I recommend dropping the View suffix from the name of the storageView property:
```
public protocol ContiguousStorage<Element>: ~Escapable {
  associatedtype Element: ~Copyable & ~Escapable

  var storage: borrow(self) StorageView<Element> { _read }
}
```
This would be a better fit with established practice in the stdlib for such properties (e.g., String.utf8, String.unicodeScalars etc.), and it helps reduce unnecessary verbosity at the point of use.
I suggest moving StorageViewIndex to a nested type, StorageView.Index. Given that the index is also generic over the same Element, it seems preferable to have only one way to spell it. Nesting the type under StorageView will also help keep the top-level namespace clean of auxiliary constructs.
Similarly, StorageViewIterator ought to be defined directly as StorageView.Iterator. (But see below.)
The attributes of borrowing iterators are not defined yet; however, I think it is unlikely we'd want to reuse the name Iterator for borrowing iteration, as it would lead to clashes. (The existing Iterator name in Sequence is semantically a consuming iterator, which cannot be implemented by this construct.) Additionally, I suspect we may not want the iterator to be (implicitly) copyable.
The MyResilientType example uses a withStorageView method that does not exist. More importantly, it may be a good idea to recommend making the core interface public (as opposed to @usableFromInline):
```
extension MyResilientType {
  // public API
  @inlinable
  public func essentialFunction(_ a: some ContiguousStorage<Element>) -> Int {
    self.essentialFunction(self.storage)
  }

  // ABI boundary
  public func essentialFunction(_ a: StorageView<Element>) -> Int {
    ...
  }
}
```
When applied to HypotheticalBase64Decoder, this leads to the following:
```
extension HypotheticalBase64Decoder {
  @inlinable
  public func decode(bytes: some ContiguousStorage<UInt8>) -> [UInt8] {
    decode(bytes: bytes.storage)
  }

  public func decode(bytes: StorageView<UInt8>) -> [UInt8] {
    ...
  }
}
```
While this does increase the API surface (so it may not be appropriate in all situations), but it is generally a good idea to expose the underlying primitives as directly as possible. (So that the API docs highlight the direct path, and so as to avoid forcing clients to go through multiple layers of unnecessary abstraction when they just want to pass a direct StorageView instance.)
The withUnsafeBufferPointer escape hatch that gets scoped access to an UBP has far more utility than simply enabling C interop -- I think it should be fully embraced as primary API. (It pairs with and goes hand in hand with the unsafe initializers.)
We'll probably want StorageView to implement this missing method from the existing Collection protocol:
```
public func index(_ i: Index, offsetBy distance: Int, limitedBy limit: Index) -> Index?
```
This method has some design problems, and it isn't at all critical for types with strideable indices, but if we provide the rest of the index navigation methods, it seems weird to omit this one.

Karl · 2024-02-14T17:39:56.896Z

Jumhyn:

I feel like UnsafeBufferPointer provides good precedent for 'buffer' as a simpler way to refer to this

The reason I suggested "Array" was actually to avoid linking those types

I don't terribly mind it, but we should consider carefully whether we want the names to suggest a relationship to unsafe buffers, or whether we would rather encourage a conceptual relationship to Array.

scanon · 2024-02-14T17:56:41.619Z

Karl:

I don't terribly mind it, but we should consider carefully whether we want the names to suggest a relationship to unsafe buffers, or whether we would rather encourage a conceptual relationship to Array.

This is effectively the safe replacement for (most uses of) UnsafeBufferPointer, so the name seems appropriate to me.

Karl · 2024-02-14T18:05:26.531Z

Yeah I'm not suggesting that it's inappropriate, I'm suggesting that there are multiple suitable candidates.

For instance, what is an Array in Swift? It's a safe, owned buffer with value semantics. This would be a safe, borrowed buffer (and I believe the intention is that we use exclusivity to suppress the spooky-modifications-at-a-distance which are the hallmark of reference semantics). So BorrowedArray also wouldn't be inappropriate IMO.

The thread about enabling bounds-checking in UBP has shown that some people habitually drop the "unsafe" prefix when discussing that type (and just call it a "buffer pointer"), leading to severe misunderstandings about how that type behaves. That's why I'm apprehensive about calling anything else a "buffer".

allevato · 2024-02-14T18:33:33.184Z

For me, using Array in the type name would hit the ear wrong for a couple reasons:

If I'm getting it from something that isn't explicitly an Array, then invoking the term "array" feels misleading. Today, there are places in Swift where—because something takes or returns an Array specifically—you end up making copies of things to fit it into a certain API. If I go from a String.UTF8View to a BorrowedArray, a reader might think "why is an 'array' involved here; did it somewhere make a copy of the UTF8View into an Array and I'm borrowing that?" On the other hand, BorrowedBuffer/StorageView/BufferView all feel more clearly like they're providing a view over that underlying storage directly.
If I'm working specifically with Array types, then BorrowedArray feels sort of too similar to ArraySlice, which I think could also lead to confusion about which one to use in each circumstance.

hassila · 2024-02-14T18:43:27.001Z

Jumhyn:

So BorrowedBuffer SGTM.

+1, that leads my mind in the right direction conceptually too.

A separate reflection is that perhaps the swift programming language book would need to get appendixes over time on concepts such as memory ownership etc more in depth, there seems to be a little tension now between keeping approachable to new users while covering “everything” - looking at memory ownership, concurrency details, macros and more - I often end up with a hunt across various sources now (pitch threads, actual proposals, discussion about the proposals, etc - as there often are critical nuggets sprinkled around…). Looking forward to when the LLM:s catch up with the latest discussions….

Karl · 2024-02-14T18:47:09.964Z

Related to this point, it's worth considering whether we might want "borrowed" versions of other standard library types.

For instance, a recent pitch suggested that we might add a type called Unicode.UTF8.ValidBufferView for text processing over non-owned storage. What if we instead called that a BorrowedString?

There would be nice some symmetry to having both BorrowedArray and BorrowedString, and I think having that as a more established pattern could minimise some of your concerns.

Anyway, I don't want to labour the point too much because my actual opinion is that BorrowedBuffer is also fine. But it's worth thinking about these things.

nixberg · 2024-02-22T16:40:34.445Z

protocol ContiguousStorage<Element>: ~Escapable

So a noncopyable type could not conform to ContiguousStorage? Is this a necessary restriction?

Also, this pitch and its sister proposal seem to imply a lifting of restrictions around generics and suppressed constraints.

scanon · 2024-02-22T17:25:39.968Z

nixberg:

Also, this pitch and its sister proposal seem to imply a lifting of restrictions around generics and suppressed constraints.

Yes, there's a forthcoming proposal that covers that.

glessard · 2024-02-22T17:31:35.322Z

nixberg:

So a noncopyable type could not conform to ContiguousStorage? Is this a necessary restriction?

No, this should also allow noncopyable types. I forgot to include the annotation in the pitch. Thanks for pointing it out!