mirror of
https://github.com/apple/swift-collections
synced 2026-11-22 04:20:40 +00:00
`TrailingArray.init(header:initializingTrailingElementsWith:)` created the value with just its header, then ran the initializer. If the initializer threw, the half-built value was destroyed, so `deinit` deinitialized all `trailingCount` elements, even though the output span had already deinitialized the ones it had initialized and the rest were never initialized. `withTemporaryValue(header:initializingTrailingElementsWith:body:)` had the same problem through the `defer` in `_withTemporaryValue`. With non-trivial elements (e.g. class references) both crashed. Initialize the trailing elements before creating the `TrailingArray`, and if the initializer throws, only deinitialize the header (and free the heap storage) before rethrowing.
456 lines
17 KiB
Swift
456 lines
17 KiB
Swift
//===----------------------------------------------------------------------===//
|
|
//
|
|
// This source file is part of the Swift Collections open source project
|
|
//
|
|
// Copyright (c) 2025 - 2026 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
|
|
//
|
|
// SPDX-License-Identifier: Apache-2.0 WITH Swift-exception
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
#if !COLLECTIONS_SINGLE_MODULE
|
|
import InternalCollectionsUtilities
|
|
#endif
|
|
|
|
/// A value that manages a contiguous block of memory starting with a header
|
|
/// value and then followed by a contiguous array of elements. Values of this
|
|
/// type own the underlying memory, and are non-copyable to ensure that
|
|
/// ownership of that memory is unique.
|
|
///
|
|
/// The number of elements stored after the header must be computable based on
|
|
/// the information in the header (via the `trailingCount` property), so that
|
|
/// it is not stored separately.
|
|
@frozen
|
|
@safe
|
|
public struct TrailingArray<Header: TrailingElements>: ~Copyable
|
|
where Header: ~Copyable
|
|
{
|
|
/// A pointer to the raw, underlying storage. This may point before the
|
|
/// Header instance in cases where the alignment of Element exceeds that
|
|
/// of the Header and we have overallocated to compensate.
|
|
@usableFromInline
|
|
@unsafe
|
|
var _storage: UnsafeMutableRawPointer
|
|
|
|
/// Pointer to the header.
|
|
@_alwaysEmitIntoClient
|
|
@unsafe
|
|
var _pointer: UnsafeMutablePointer<Header> {
|
|
unsafe Self.headerPointer(fromStorage: _storage)
|
|
}
|
|
|
|
/// The element type stored within the buffer.
|
|
public typealias Element = Header.Element
|
|
|
|
/// Allocate storage and initialize only the header, leaving the trailing
|
|
/// elements uninitialized. This is private because it can compromise
|
|
/// memory safety.
|
|
@_alwaysEmitIntoClient
|
|
private init(_headerOnly header: consuming Header) {
|
|
let (bytes, alignment) = Self.allocationSize(header: header)
|
|
unsafe _storage = UnsafeMutableRawPointer.allocate(
|
|
byteCount: bytes,
|
|
alignment: alignment)
|
|
|
|
unsafe _pointer.initialize(to: header)
|
|
}
|
|
|
|
/// Initialize the trailing elements that follow the header at `pointer`.
|
|
///
|
|
/// If `initializer` throws, the output span deinitializes the elements it
|
|
/// has initialized so far, so the caller only needs to clean up the header.
|
|
@available(SwiftStdlib 5.1, *)
|
|
@_alwaysEmitIntoClient
|
|
@unsafe
|
|
static func _initializeTrailingElements<E>(
|
|
after pointer: UnsafeMutablePointer<Header>,
|
|
initializer: (inout OutputSpan<Element>) throws(E) -> Void
|
|
) throws(E) {
|
|
let elements = unsafe _elements(after: pointer)
|
|
var output = unsafe OutputSpan(buffer: elements, initializedCount: 0)
|
|
try initializer(&output)
|
|
let initialized = unsafe output.finalize(for: elements)
|
|
precondition(
|
|
elements.count == initialized, "TrailingArray initialization underflow")
|
|
}
|
|
|
|
/// Allocate an intrusive managed buffer with the given header and calling
|
|
/// the initializer to fill in the trailing elements.
|
|
@available(SwiftStdlib 5.1, *)
|
|
@_alwaysEmitIntoClient
|
|
public init<E>(
|
|
header: consuming Header,
|
|
initializingTrailingElementsWith initializer: (inout OutputSpan<Element>) throws(E) -> Void
|
|
) throws(E) {
|
|
let (bytes, alignment) = Self.allocationSize(header: header)
|
|
let storage = unsafe UnsafeMutableRawPointer.allocate(
|
|
byteCount: bytes,
|
|
alignment: alignment)
|
|
let pointer = unsafe Self.headerPointer(fromStorage: storage)
|
|
unsafe pointer.initialize(to: header)
|
|
do throws(E) {
|
|
try unsafe Self._initializeTrailingElements(
|
|
after: pointer, initializer: initializer)
|
|
} catch {
|
|
// The trailing elements aren't initialized, so don't let `deinit` run.
|
|
unsafe pointer.deinitialize(count: 1)
|
|
unsafe storage.deallocate()
|
|
throw error
|
|
}
|
|
unsafe self._storage = storage
|
|
}
|
|
|
|
/// Allocate an intrusive managed buffer with the given header and
|
|
/// initializing each trailing element with the given `element`.
|
|
@_alwaysEmitIntoClient
|
|
public init(header: consuming Header, repeating element: Element) {
|
|
self.init(_headerOnly: header)
|
|
unsafe rawElements.initialize(repeating: element)
|
|
}
|
|
|
|
/// Deinitialize each of the trailing elements, then the header, then
|
|
/// deallocate the underlying storage.
|
|
@_alwaysEmitIntoClient
|
|
deinit {
|
|
unsafe rawElements.deinitialize()
|
|
unsafe _pointer.deinitialize(count: 1)
|
|
unsafe _storage.deallocate()
|
|
}
|
|
|
|
/// Take ownership over a pointer to memory containing the header followed
|
|
/// by the trailing elements.
|
|
///
|
|
/// Once this managed buffer instance is no longer used, this memory will
|
|
/// be freed.
|
|
/// - Parameters:
|
|
/// - pointer: A pointer to the header, which should already have been
|
|
/// initialized by the caller.
|
|
/// - storage: A pointer to the storage containing the header and
|
|
/// pointers. This will usually be `UnsafeMutableRawPointer(pointer)`,
|
|
/// but may precede `pointer` if the elements have greater alignment
|
|
/// than the header.
|
|
@_alwaysEmitIntoClient
|
|
public init(
|
|
consuming pointer: UnsafeMutablePointer<Header>,
|
|
storage: UnsafeMutableRawPointer
|
|
) {
|
|
unsafe self._storage = storage
|
|
precondition(
|
|
unsafe self._pointer == pointer,
|
|
"header pointer does not account for the alignment of the elements"
|
|
)
|
|
}
|
|
|
|
/// Return the pointer to the underlying memory, including ownership over
|
|
/// that memory. The underlying storage will not be freed by this buffer;
|
|
/// it is the responsibility of the caller. The header pointer and
|
|
/// underlying storage are returned separately, to handle cases where
|
|
/// the alignment of the elements is greater than that of the header.
|
|
@_alwaysEmitIntoClient
|
|
public consuming func leakStorage() -> (
|
|
pointer: UnsafeMutablePointer<Header>,
|
|
storage: UnsafeMutableRawPointer
|
|
) {
|
|
let pointer = unsafe self._pointer
|
|
let storage = unsafe _storage
|
|
discard self
|
|
return unsafe (pointer, storage)
|
|
}
|
|
|
|
/// Access the header portion of the buffer.
|
|
@_alwaysEmitIntoClient
|
|
public var header: Header {
|
|
unsafeAddress {
|
|
unsafe UnsafePointer(_pointer)
|
|
}
|
|
|
|
unsafeMutableAddress {
|
|
unsafe _pointer
|
|
}
|
|
}
|
|
|
|
/// The number of trailing elements in the value.
|
|
@_alwaysEmitIntoClient
|
|
public var count: Int { header.trailingCount }
|
|
|
|
/// Starting index for accessing the trailing elements. Always 0
|
|
@_alwaysEmitIntoClient
|
|
public var startIndex: Int { 0 }
|
|
|
|
/// Ending index for accessing the trailing elements. Always `count`.
|
|
@_alwaysEmitIntoClient
|
|
public var endIndex: Int { count }
|
|
|
|
/// Indices covering all of the trailing elements. Always `0..<count`.
|
|
@_alwaysEmitIntoClient
|
|
public var indices: Range<Int> { 0 ..< count }
|
|
|
|
/// Access the trailing element at the given index.
|
|
@_alwaysEmitIntoClient
|
|
public subscript(index: Int) -> Element {
|
|
get {
|
|
precondition(index >= 0 && index < count)
|
|
return unsafe rawElements[index]
|
|
}
|
|
|
|
set {
|
|
precondition(index >= 0 && index < count)
|
|
unsafe rawElements[index] = newValue
|
|
}
|
|
}
|
|
|
|
/// Access the flexible array elements.
|
|
@_alwaysEmitIntoClient
|
|
@unsafe
|
|
var rawElements: UnsafeMutableBufferPointer<Element> {
|
|
unsafe Self._elements(after: _pointer)
|
|
}
|
|
|
|
@_alwaysEmitIntoClient
|
|
@unsafe
|
|
static func _elements(
|
|
after pointer: UnsafeMutablePointer<Header>
|
|
) -> UnsafeMutableBufferPointer<Element> {
|
|
unsafe UnsafeMutableBufferPointer(
|
|
start: UnsafeMutableRawPointer(pointer.advanced(by: 1))
|
|
.assumingMemoryBound(to: Element.self),
|
|
count: pointer.pointee.trailingCount
|
|
)
|
|
}
|
|
|
|
/// Accesses the trailing elements following the header.
|
|
@available(SwiftStdlib 5.1, *)
|
|
@_alwaysEmitIntoClient
|
|
public var elements: Span<Element> {
|
|
@_lifetime(self)
|
|
get {
|
|
unsafe _overrideLifetime(rawElements.span, borrowing: self)
|
|
}
|
|
}
|
|
|
|
/// Accesses the trailing elements following the header, allowing mutation
|
|
/// of those elements.
|
|
@available(SwiftStdlib 5.1, *)
|
|
@_alwaysEmitIntoClient
|
|
public var mutableElements: MutableSpan<Element> {
|
|
@_lifetime(self)
|
|
mutating get {
|
|
let elements = unsafe self.rawElements.mutableSpan
|
|
return unsafe _overrideLifetime(elements, mutating: &self)
|
|
}
|
|
}
|
|
|
|
/// Execute the given closure, providing it with an unsafe buffer pointer
|
|
/// referencing the header.
|
|
@_alwaysEmitIntoClient
|
|
public mutating func withUnsafeMutablePointerToHeader<E, R: ~Copyable>(
|
|
_ body: (UnsafeMutablePointer<Header>) throws(E) -> R
|
|
) throws(E) -> R {
|
|
return unsafe try body(_pointer)
|
|
}
|
|
|
|
/// Execute the given closure, providing it with an unsafe buffer pointer
|
|
/// referencing the trailing elements.
|
|
@_alwaysEmitIntoClient
|
|
public mutating func withUnsafeMutablePointerToElements<E, R: ~Copyable>(
|
|
_ body: (UnsafeMutableBufferPointer<Element>) throws(E) -> R
|
|
) throws(E) -> R {
|
|
return unsafe try body(rawElements)
|
|
}
|
|
|
|
/// Execute the given closure, providing it with unsafe pointers to the
|
|
/// header and trailing elements, respectively.
|
|
@_alwaysEmitIntoClient
|
|
public mutating func withUnsafeMutablePointers<E, R: ~Copyable>(
|
|
_ body: (UnsafeMutablePointer<Header>, UnsafeMutableBufferPointer<Element>) throws(E) -> R
|
|
) throws(E) -> R {
|
|
return unsafe try body(_pointer, rawElements)
|
|
}
|
|
|
|
/// Determine the allocation size and alignment needed for the given header
|
|
/// value along with its trailing elements.
|
|
///
|
|
/// In cases where the element's alignment exceeds that of the header,
|
|
/// this operation will suggest overallocation so that the elements can be
|
|
/// properly aligned following the header.
|
|
@_alwaysEmitIntoClient
|
|
static func allocationSize(header: borrowing Header) -> (size: Int, alignment: Int) {
|
|
// The number of bytes needed to contain the header and elements,
|
|
// assuming that there are no alignment issues.
|
|
let numBytes = MemoryLayout<Header>.stride + MemoryLayout<Element>.stride * header.trailingCount
|
|
|
|
let headerAlignment = MemoryLayout<Header>.alignment
|
|
let elementAlignment = MemoryLayout<Element>.alignment
|
|
|
|
// If the header provides sufficient alignment for the elements,
|
|
// we're done.
|
|
if elementAlignment <= headerAlignment {
|
|
return (numBytes, MemoryLayout<Header>.alignment)
|
|
}
|
|
|
|
// We may have to slide an allocation by up to the difference between
|
|
// the element and header alignments to ensure that the elements are
|
|
// appropriately aligned.
|
|
return (
|
|
numBytes + elementAlignment - headerAlignment,
|
|
MemoryLayout<Element>.alignment)
|
|
}
|
|
|
|
/// Given storage that is large enough to accommodate padding + the header
|
|
/// + the elements, return the header pointer from the storage pointer.
|
|
@_alwaysEmitIntoClient
|
|
static func headerPointer(fromStorage storage: UnsafeMutableRawPointer) -> UnsafeMutablePointer<Header> {
|
|
let headerAlignment = MemoryLayout<Header>.alignment
|
|
let elementAlignment = MemoryLayout<Element>.alignment
|
|
|
|
// Normal case: the header has sufficient alignment to include the
|
|
// elements, so the storage refers directly to the header.
|
|
if elementAlignment <= headerAlignment {
|
|
return unsafe storage.assumingMemoryBound(to: Header.self)
|
|
}
|
|
|
|
// The header is stored right before the elements, with padding bytes
|
|
// between the start of the allocation and up to the header.
|
|
return unsafe storage.advanced(by: MemoryLayout<Header>.stride)
|
|
.alignedUp(for: Element.self)
|
|
.advanced(by: -MemoryLayout<Header>.stride)
|
|
.assumingMemoryBound(to: Header.self)
|
|
}
|
|
}
|
|
|
|
extension TrailingArray where Header: ~Copyable, Header.Element: BitwiseCopyable {
|
|
/// Allocate an intrusive managed buffer with the given header, but leaving the
|
|
/// trailing elements uninitialized.
|
|
@_alwaysEmitIntoClient
|
|
@unsafe
|
|
public init(header: consuming Header, uninitializedTrailingElements: ()) {
|
|
self.init(_headerOnly: header)
|
|
}
|
|
}
|
|
|
|
extension TrailingArray where Header: Copyable {
|
|
/// Create a temporary intrusive managed buffer for the given header, whose
|
|
/// trailing elements are initialized to copies of `element`. That instance
|
|
/// is provided to the given `body` to operate on for the duration of the
|
|
/// call. The temporary is allocated on the stack, unless it is very
|
|
/// large according to `withUnsafeTemporaryAllocation`.
|
|
@_alwaysEmitIntoClient
|
|
public static func withTemporaryValue<R: ~Copyable, E>(
|
|
header: consuming Header,
|
|
repeating element: Element,
|
|
body: (inout TrailingArray<Header>) throws(E) -> R
|
|
) throws(E) -> R {
|
|
return unsafe try _withTemporaryValue(
|
|
header: header, uninitializedTrailingElements: ()
|
|
) { (value) throws(E) in
|
|
unsafe value.rawElements.initialize(repeating: element)
|
|
return try body(&value)
|
|
}
|
|
}
|
|
|
|
/// Create a temporary intrusive managed buffer for the given header, whose
|
|
/// trailing elements are initialized with the given `initializer` function.
|
|
/// That instance is provided to the given `body` to operate on for the
|
|
/// duration of the call. The temporary is allocated on the stack, unless
|
|
/// it is very large according to `withUnsafeTemporaryAllocation`.
|
|
@available(SwiftStdlib 5.1, *)
|
|
@_alwaysEmitIntoClient
|
|
public static func withTemporaryValue<R: ~Copyable, E>(
|
|
header: consuming Header,
|
|
initializingTrailingElementsWith initializer: (inout OutputSpan<Element>) throws(E) -> Void,
|
|
body: (inout TrailingArray<Header>) throws(E) -> R
|
|
) throws(E) -> R {
|
|
return unsafe try _withTemporaryValue(
|
|
header: header,
|
|
uninitializedTrailingElements: (),
|
|
initializingTrailingElements: { (pointer) throws(E) in
|
|
try unsafe _initializeTrailingElements(
|
|
after: pointer, initializer: initializer)
|
|
},
|
|
body: body)
|
|
}
|
|
}
|
|
|
|
extension TrailingArray {
|
|
/// Create a temporary intrusive managed buffer for the given header, whose
|
|
/// trailing elements are left uninitialized. That instance is provided to
|
|
/// the given `body` to operate on for the duration of the
|
|
/// call. The temporary is allocated on the stack, unless it is very
|
|
/// large according to `withUnsafeTemporaryAllocation`.
|
|
@_alwaysEmitIntoClient
|
|
@unsafe
|
|
static func _withTemporaryValue<R: ~Copyable, E>(
|
|
header: Header,
|
|
uninitializedTrailingElements: (),
|
|
initializingTrailingElements: (
|
|
UnsafeMutablePointer<Header>
|
|
) throws(E) -> Void = { _ in },
|
|
body: (inout TrailingArray<Header>) throws(E) -> R
|
|
) throws(E) -> R {
|
|
let (numBytes, alignment) = allocationSize(header: header)
|
|
|
|
// Allocate temporary storage large enough for the value we need.
|
|
return try _withUnsafeTemporaryAllocation(
|
|
byteCount: numBytes,
|
|
alignment: alignment
|
|
) { buffer throws(E) in
|
|
// Initialize the header within the temporary allocation.
|
|
let storagePointer = buffer.baseAddress!
|
|
let headerPointer = unsafe TrailingArray.headerPointer(fromStorage: storagePointer)
|
|
unsafe headerPointer.initialize(to: header)
|
|
|
|
// Initialize the trailing elements, if requested, before creating the
|
|
// trailing array, so a throwing initializer doesn't leave behind
|
|
// a value whose elements aren't initialized.
|
|
do throws(E) {
|
|
try initializingTrailingElements(headerPointer)
|
|
} catch {
|
|
unsafe headerPointer.deinitialize(count: 1)
|
|
throw error
|
|
}
|
|
|
|
/// Create a trailing array over that temporary storage.
|
|
var managedBuffer: Optional = unsafe TrailingArray(
|
|
consuming: headerPointer,
|
|
storage: storagePointer)
|
|
|
|
defer {
|
|
let buffer = managedBuffer.take()!
|
|
// Deinitialize the elements and header.
|
|
unsafe buffer.rawElements.deinitialize()
|
|
unsafe buffer._pointer.deinitialize(count: 1)
|
|
|
|
// Tell the trailing buffer not to free the storage.
|
|
let (finalPointer, finalStorage) = unsafe buffer.leakStorage()
|
|
precondition(unsafe finalPointer == headerPointer)
|
|
precondition(unsafe finalStorage == storagePointer)
|
|
}
|
|
return try body(&managedBuffer!)
|
|
}
|
|
}
|
|
}
|
|
|
|
extension TrailingArray where Header.Element: BitwiseCopyable {
|
|
/// Create a temporary intrusive managed buffer for the given header, whose
|
|
/// trailing elements are left uninitialized. That instance is provided to
|
|
/// the given `body` to operate on for the duration of the
|
|
/// call. The temporary is allocated on the stack, unless it is very
|
|
/// large according to `withUnsafeTemporaryAllocation`.
|
|
@_alwaysEmitIntoClient
|
|
@unsafe
|
|
public static func withTemporaryValue<R: ~Copyable, E>(
|
|
header: consuming Header,
|
|
uninitializedTrailingElements: (),
|
|
body: (inout TrailingArray<Header>) throws(E) -> R
|
|
) throws(E) -> R {
|
|
return unsafe try _withTemporaryValue(
|
|
header: header, uninitializedTrailingElements: ()
|
|
) { (value) throws(E) in
|
|
try body(&value)
|
|
}
|
|
}
|
|
}
|