mirror of
https://github.com/apple/swift-async-algorithms
synced 2026-11-22 04:10:40 +00:00
* Move platform requirements to availability annotations Adding or raising the deployment platforms in the package manifest is a SemVer major breaking change as consumers must also add or raise their deployment platforms. This is a known limitation of SwiftPM. Unforunately this means that it's very difficult for non-leaf packages to adopt packages which declare their platforms in the manifest. Doing so puts the brakes on adoption and ecosystem growth. For 'core' packages like this one availability constraints should be expressed on declarations rather than in the manifest. This patch adds equivalent availability annotations to declarations across the package and removes platforms from the package manifest. * Address naming feedback
144 lines
4.8 KiB
Swift
144 lines
4.8 KiB
Swift
//===----------------------------------------------------------------------===//
|
|
//
|
|
// This source file is part of the Swift Async Algorithms open source project
|
|
//
|
|
// Copyright (c) 2022 Apple Inc. and the Swift project authors
|
|
// Licensed under Apache License v2.0 with Runtime Library Exception
|
|
//
|
|
// See https://swift.org/LICENSE.txt for license information
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
/// An `AsyncIterator` that provides a convenient and high-performance implementation
|
|
/// of a common architecture for `AsyncSequence` of `UInt8`, otherwise known as byte streams.
|
|
///
|
|
/// Bytes are read into an internal buffer of `capacity` bytes via the
|
|
/// `readFunction`. Invoking `next()` returns bytes from the internal buffer until it's
|
|
/// empty, and then suspends and awaits another invocation of `readFunction` to
|
|
/// refill. If `readFunction` returns 0 (indicating nothing was read), `next()` will
|
|
/// return `nil` from then on. Cancellation is checked before each invocation of
|
|
/// `readFunction`, which means that many calls to `next()` will not check for
|
|
/// cancellation.
|
|
///
|
|
/// A typical use of `AsyncBufferedByteIterator` looks something like this:
|
|
///
|
|
/// struct AsyncBytes: AsyncSequence {
|
|
/// public typealias Element = UInt8
|
|
/// var handle: ReadableThing
|
|
///
|
|
/// internal init(_ readable: ReadableThing) {
|
|
/// handle = readable
|
|
/// }
|
|
///
|
|
/// public func makeAsyncIterator() -> AsyncBufferedByteIterator {
|
|
/// return AsyncBufferedByteIterator(capacity: 16384) { buffer in
|
|
/// // This runs once every 16384 invocations of next()
|
|
/// return try await handle.read(into: buffer)
|
|
/// }
|
|
/// }
|
|
/// }
|
|
///
|
|
///
|
|
@available(AsyncAlgorithms 1.0, *)
|
|
public struct AsyncBufferedByteIterator: AsyncIteratorProtocol {
|
|
public typealias Element = UInt8
|
|
@usableFromInline var buffer: _AsyncBytesBuffer
|
|
|
|
/// Creates an asynchronous buffered byte iterator with a specified capacity and read function.
|
|
///
|
|
/// - Parameters:
|
|
/// - capacity: The maximum number of bytes that a single invocation of `readFunction` may produce.
|
|
/// This is the allocated capacity of the backing buffer for iteration; the value must be greater than 0.
|
|
/// - readFunction: The function for refilling the buffer.
|
|
public init(
|
|
capacity: Int,
|
|
readFunction: @Sendable @escaping (UnsafeMutableRawBufferPointer) async throws -> Int
|
|
) {
|
|
buffer = _AsyncBytesBuffer(capacity: capacity, readFunction: readFunction)
|
|
}
|
|
|
|
/// Reads a byte out of the buffer if available. When no bytes are available, this will trigger
|
|
/// the read function to reload the buffer and then return the next byte from that buffer.
|
|
@inlinable @inline(__always)
|
|
public mutating func next() async throws -> UInt8? {
|
|
return try await buffer.next()
|
|
}
|
|
}
|
|
|
|
@available(*, unavailable)
|
|
extension AsyncBufferedByteIterator: Sendable {}
|
|
|
|
@available(AsyncAlgorithms 1.0, *)
|
|
@frozen @usableFromInline
|
|
internal struct _AsyncBytesBuffer {
|
|
@usableFromInline
|
|
final class Storage {
|
|
fileprivate let buffer: UnsafeMutableRawBufferPointer
|
|
|
|
init(
|
|
capacity: Int
|
|
) {
|
|
precondition(capacity > 0)
|
|
buffer = UnsafeMutableRawBufferPointer.allocate(
|
|
byteCount: capacity,
|
|
alignment: MemoryLayout<AnyObject>.alignment
|
|
)
|
|
}
|
|
|
|
deinit {
|
|
buffer.deallocate()
|
|
}
|
|
}
|
|
|
|
@usableFromInline internal let storage: Storage
|
|
@usableFromInline internal var nextPointer: UnsafeRawPointer
|
|
@usableFromInline internal var endPointer: UnsafeRawPointer
|
|
|
|
internal let readFunction: @Sendable (UnsafeMutableRawBufferPointer) async throws -> Int
|
|
internal var finished = false
|
|
|
|
@usableFromInline init(
|
|
capacity: Int,
|
|
readFunction: @Sendable @escaping (UnsafeMutableRawBufferPointer) async throws -> Int
|
|
) {
|
|
let s = Storage(capacity: capacity)
|
|
self.readFunction = readFunction
|
|
storage = s
|
|
nextPointer = UnsafeRawPointer(s.buffer.baseAddress!)
|
|
endPointer = nextPointer
|
|
}
|
|
|
|
@inline(never) @usableFromInline
|
|
internal mutating func reloadBufferAndNext() async throws -> UInt8? {
|
|
if finished {
|
|
return nil
|
|
}
|
|
try Task.checkCancellation()
|
|
do {
|
|
let readSize: Int = try await readFunction(storage.buffer)
|
|
if readSize == 0 {
|
|
finished = true
|
|
nextPointer = endPointer
|
|
return nil
|
|
}
|
|
nextPointer = UnsafeRawPointer(storage.buffer.baseAddress!)
|
|
endPointer = nextPointer + readSize
|
|
} catch {
|
|
finished = true
|
|
nextPointer = endPointer
|
|
throw error
|
|
}
|
|
return try await next()
|
|
}
|
|
|
|
@inlinable @inline(__always)
|
|
internal mutating func next() async throws -> UInt8? {
|
|
if _fastPath(nextPointer != endPointer) {
|
|
let byte = nextPointer.load(fromByteOffset: 0, as: UInt8.self)
|
|
nextPointer = nextPointer + 1
|
|
return byte
|
|
}
|
|
return try await reloadBufferAndNext()
|
|
}
|
|
}
|