mirror of
https://github.com/apple/swift-collections
synced 2026-11-22 04:20:40 +00:00
144 lines
5.3 KiB
Swift
144 lines
5.3 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
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
/// Represents memory containing a header value followed by some extra padding
|
|
/// following it. Values of this type own the underlying memory, and are
|
|
/// non-copyable to ensure that ownership of that memory is unique. Memory
|
|
/// allocated for the storage will be deinitialized and freed when the
|
|
/// padded-storage instance is deinitialized.
|
|
///
|
|
/// The extra padding referenced by this value is allocated, but is otherwise
|
|
/// inaccessible except through unsafe pointer manipulation. This is intended
|
|
/// to be used in cases where a common header can have some extra storage
|
|
/// following it, but that storage is not describable using the type
|
|
/// system or is otherwise opaque to the user.
|
|
///
|
|
/// If the storage following the header is contiguous memory of some specific
|
|
/// type, whose count is computable from the header, use
|
|
/// `IntrusiveManagedPointer` instead.
|
|
@frozen
|
|
public struct TrailingPadding<Header: ~Copyable>: ~Copyable {
|
|
/// Pointer to the header, followed by the padding.
|
|
@usableFromInline
|
|
let _pointer: UnsafeMutablePointer<Header>
|
|
|
|
/// Create a new instance with the given header and total size. The total
|
|
/// size includes the storage for the header itself, so it must be at least
|
|
/// as large as the header.
|
|
@_alwaysEmitIntoClient
|
|
public init(header: consuming Header, totalSize size: Int) {
|
|
precondition(size >= MemoryLayout<Header>.size,
|
|
"must allocate enough storage for the underlying stored type")
|
|
_pointer = UnsafeMutableRawPointer
|
|
.allocate(byteCount: size, alignment: MemoryLayout<Header>.alignment)
|
|
.assumingMemoryBound(to: Header.self)
|
|
_pointer.initialize(to: header)
|
|
}
|
|
|
|
/// Take ownership over a pointer to memory containing the header followed
|
|
/// by the trailing elements.
|
|
///
|
|
/// Once this padded storage is no longer used, this memory will be
|
|
/// deinitialized and freed.
|
|
@_alwaysEmitIntoClient
|
|
public init(consuming pointer: UnsafeMutablePointer<Header>) {
|
|
self._pointer = pointer
|
|
}
|
|
|
|
/// Deinitializes the header, then deallocates the underlying memory.
|
|
@_alwaysEmitIntoClient
|
|
deinit {
|
|
_pointer.deinitialize(count: 1)
|
|
_pointer.deallocate()
|
|
}
|
|
|
|
/// Access the header portion of the value.
|
|
@_alwaysEmitIntoClient
|
|
public var header: Header {
|
|
unsafeAddress {
|
|
UnsafePointer(_pointer)
|
|
}
|
|
|
|
unsafeMutableAddress {
|
|
_pointer
|
|
}
|
|
}
|
|
|
|
/// Executes the given closure with the pointer to the header itself.
|
|
@_alwaysEmitIntoClient
|
|
public func withUnsafeMutablePointerToHeader<R: ~Copyable, E>(
|
|
_ body: (UnsafeMutablePointer<Header>) throws(E) -> R
|
|
) throws(E) -> R {
|
|
return try body(_pointer)
|
|
}
|
|
|
|
/// Take ownership over the stored memory, returning its pointer. The
|
|
/// underlying storage will not be freed by the `TrailingPadding` instance,
|
|
/// as it is the responsibility of the caller.
|
|
@_alwaysEmitIntoClient
|
|
public consuming func leakStorage() -> UnsafeMutablePointer<Header> {
|
|
let pointer = self._pointer
|
|
discard self
|
|
return pointer
|
|
}
|
|
}
|
|
|
|
extension TrailingPadding: @unchecked Sendable
|
|
where Header: Sendable, Header: ~Copyable { }
|
|
|
|
extension TrailingPadding where Header: Copyable {
|
|
/// Create a temporary for the given header with additional storage,
|
|
/// providing that instance to the given `body` to operate on for the
|
|
/// duration. The temporary is allocated on the stack (unless it is very
|
|
/// large), eliminating the need for heap allocation of variable-size
|
|
/// values.
|
|
@_alwaysEmitIntoClient
|
|
public static func withTemporaryValue<R: ~Copyable, E>(
|
|
header: Header,
|
|
totalSize size: Int,
|
|
body: (inout TrailingPadding<Header>) throws(E) -> R
|
|
) throws(E) -> R {
|
|
precondition(size >= MemoryLayout<Header>.size,
|
|
"must allocate enough storage for the underlying stored type")
|
|
|
|
// Allocate temporary storage large enough for the value we need.
|
|
let result: Result<R, E> = withUnsafeTemporaryAllocation(
|
|
byteCount: size,
|
|
alignment: MemoryLayout<Header>.alignment
|
|
) { buffer in
|
|
/// Create a tail-allocated storage over that temporary storage.
|
|
let pointer = buffer.baseAddress!.assumingMemoryBound(to: Header.self)
|
|
pointer.initialize(to: header)
|
|
var tailAllocated = TrailingPadding(consuming: pointer)
|
|
|
|
do throws(E) {
|
|
let result = try body(&tailAllocated)
|
|
|
|
// Tell the tail-allocated buffer not to free the storage.
|
|
let finalPointer = tailAllocated.leakStorage()
|
|
precondition(finalPointer == pointer)
|
|
|
|
return .success(result)
|
|
} catch {
|
|
// Tell the tail-allocated buffer not to free the storage.
|
|
let finalPointer = tailAllocated.leakStorage()
|
|
precondition(finalPointer == pointer)
|
|
|
|
return .failure(error)
|
|
}
|
|
}
|
|
|
|
return try result.get()
|
|
}
|
|
}
|