Add some spans to ByteBuffer (#3371)

Motivation:

Users would like to be able to access the underlying memory of a
ByteBuffer, as evidenced by the plethora of `withUnsafe*` methods that
ByteBuffer has. As Swift 6.2 has introduced some initial APIs for safe
memory access to underlying storage, we should offer similar APIs on
ByteBuffer to enable users to get safer access to that storage.

For now, the obvious APIs to be able to supplement are:

- withUnsafeReadableBytes
- withUnsafeMutableReadableBytes
- writeWithUnsafeMutableWritableBytes

We can also offer some new APIs to allow initializing a buffer directly
from an OutputSpan.

Note that we can only do this because the Language Steering Group has
pinky promised that they will not break the "Lifetimes" experimental
feature: see

https://forums.swift.org/t/experimental-support-for-lifetime-dependencies-in-swift-6-2-and-beyond/78638
for more details. We are taking them at their word, and so we are
enabling that feature.

Modifications:

Many new methods and tests.

Result:

Safer access.

Author: Lukasa

Package.swift

@@ -23,7 +23,13 @@ let swiftSystem: PackageDescription.Target.Dependency = .product(name: "SystemPa
 // compatibility with previous NIO versions.
 let historicalNIOPosixDependencyRequired: [Platform] = [.macOS, .iOS, .tvOS, .watchOS, .linux, .android]
 
-let swiftSettings: [SwiftSetting] = []
+let swiftSettings: [SwiftSetting] = [
+    // The Language Steering Group has promised that they won't break the APIs that currently exist under
+    // this "experimental" feature flag without two subsequent releases. We assume they will respect that
+    // promise, so we enable this here. For more, see:
+    // https://forums.swift.org/t/experimental-support-for-lifetime-dependencies-in-swift-6-2-and-beyond/78638
+    .enableExperimentalFeature("Lifetimes")
+]
 
 // This doesn't work when cross-compiling: the privacy manifest will be included in the Bundle and
 // Foundation will be linked. This is, however, strictly better than unconditionally adding the

Sources/NIOCore/ByteBuffer-aux.swift

@@ -832,6 +832,36 @@ extension ByteBuffer {
         self = ByteBufferAllocator().buffer(dispatchData: dispatchData)
     }
     #endif
+
+    #if compiler(>=6.2)
+    /// Create a fresh ``ByteBuffer`` with a minimum size, and initializing it safely via an `OutputSpan`.
+    ///
+    /// This will allocate a new ``ByteBuffer`` with at least `capacity` bytes of storage, and then calls
+    /// `initializer` with an `OutputSpan` over the entire allocated storage. This is a convenient method
+    /// to initialize a buffer directly and safely in a single allocation, including from C code.
+    ///
+    /// Once this call returns, the buffer will have its ``ByteBuffer/writerIndex`` appropriately advanced to encompass
+    /// any memory initialized by the `initializer`. Uninitialized memory will be after the ``ByteBuffer/writerIndex``,
+    /// available for subsequent use.
+    ///
+    /// - info: If you have access to a `Channel`, `ChannelHandlerContext`, or `ByteBufferAllocator` we
+    ///         recommend using `channel.allocator.buffer(capacity:initializingWith:)`. Or if you want to write multiple items into
+    ///         the buffer use `channel.allocator.buffer(capacity: ...)` to allocate a `ByteBuffer` of the right
+    ///         size followed by a `write(minimumWritableBytes:initializingWith:)` instead of using this method. This allows SwiftNIO to do
+    ///         accounting and optimisations of resources acquired for operations on a given `Channel` in the future.
+    ///
+    /// - parameters:
+    ///     - capacity: The minimum initial space to allocate for the buffer.
+    ///     - initializer: The initializer that will be invoked to initialize the allocated memory.
+    @inlinable
+    @available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
+    public init<ErrorType: Error>(
+        initialCapacity capacity: Int,
+        initializingWith initializer: (_ span: inout OutputRawSpan) throws(ErrorType) -> Void
+    ) throws(ErrorType) {
+        self = try ByteBufferAllocator().buffer(capacity: capacity, initializingWith: initializer)
+    }
+    #endif
 }
 
 extension ByteBuffer: Codable {
@@ -971,6 +1001,32 @@ extension ByteBufferAllocator {
         return buffer
     }
     #endif
+
+    #if compiler(>=6.2)
+    /// Create a fresh ``ByteBuffer`` with a minimum size, and initializing it safely via an `OutputSpan`.
+    ///
+    /// This will allocate a new ``ByteBuffer`` with at least `capacity` bytes of storage, and then calls
+    /// `initializer` with an `OutputSpan` over the entire allocated storage. This is a convenient method
+    /// to initialize a buffer directly and safely in a single allocation, including from C code.
+    ///
+    /// Once this call returns, the buffer will have its ``ByteBuffer/writerIndex`` appropriately advanced to encompass
+    /// any memory initialized by the `initializer`. Uninitialized memory will be after the ``ByteBuffer/writerIndex``,
+    /// available for subsequent use.
+    ///
+    /// - parameters:
+    ///     - capacity: The minimum initial space to allocate for the buffer.
+    ///     - initializer: The initializer that will be invoked to initialize the allocated memory.
+    @inlinable
+    @available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
+    public func buffer<ErrorType: Error>(
+        capacity: Int,
+        initializingWith initializer: (_ span: inout OutputRawSpan) throws(ErrorType) -> Void
+    ) throws(ErrorType) -> ByteBuffer {
+        var buffer = self.buffer(capacity: capacity)
+        try buffer.writeWithOutputRawSpan(minimumWritableBytes: capacity, initializingWith: initializer)
+        return buffer
+    }
+    #endif
 }
 
 extension Optional where Wrapped == ByteBuffer {

Sources/NIOCore/ByteBuffer-core.swift

@@ -691,6 +691,52 @@ public struct ByteBuffer {
         return try body(.init(rebasing: self._slicedStorageBuffer[range]))
     }
 
+    #if compiler(>=6.2)
+    /// Provides safe high-performance read-only access to the readable bytes of this buffer.
+    @inlinable
+    @available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
+    public var readableBytesSpan: RawSpan {
+        @_lifetime(borrow self)
+        borrowing get {
+            let range = Range<Int>(uncheckedBounds: (lower: self.readerIndex, upper: self.writerIndex))
+            return _overrideLifetime(RawSpan(_unsafeBytes: self._slicedStorageBuffer[range]), borrowing: self)
+        }
+    }
+
+    /// Provides mutable access to the readable bytes of this buffer.
+    @inlinable
+    @available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
+    public var mutableReadableBytesSpan: MutableRawSpan {
+        @_lifetime(&self)
+        mutating get {
+            self._copyStorageAndRebaseIfNeeded()
+            let range = Range<Int>(uncheckedBounds: (lower: self.readerIndex, upper: self.writerIndex))
+            return _overrideLifetime(MutableRawSpan(_unsafeBytes: self._slicedStorageBuffer[range]), mutating: &self)
+        }
+    }
+
+    /// Enables high-performance low-level appending into the writable section of this buffer.
+    ///
+    /// The writer index will be advanced by the number of bytes written into the
+    /// `OutputRawSpan`.
+    ///
+    /// - parameters:
+    ///     - minimumWritableBytes: The minimum initial space to allocate for the buffer.
+    ///     - initializer: The initializer that will be invoked to initialize the allocated memory.
+    @inlinable
+    @available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
+    public mutating func writeWithOutputRawSpan<ErrorType: Error>(
+        minimumWritableBytes: Int,
+        initializingWith initializer: (_ span: inout OutputRawSpan) throws(ErrorType) -> Void
+    ) throws(ErrorType) {
+        try self.writeWithUnsafeMutableBytes(minimumWritableBytes: minimumWritableBytes) { ptr throws(ErrorType) in
+            var span = OutputRawSpan(buffer: ptr, initializedCount: 0)
+            try initializer(&span)
+            return span.byteCount
+        }
+    }
+    #endif
+
     /// Yields the bytes currently writable (`bytesWritable` = `capacity` - `writerIndex`). Before reading those bytes you must first
     /// write to them otherwise you will trigger undefined behaviour. The writer index will remain unchanged.
     ///