Add some spans to ByteBuffer

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.
     ///