Files
swift-collections/Sources/TrailingElementsModule/TrailingPadding.swift
T
Karoy Lorentey 1b936eda0b Disable strict memory safety on older toolchains
It would take too much effort to try to mitigate stdlib differences.

Fix low-hanging warnings, but turn off `.strictMemorySafety` on older toolchains by splitting the package manifest.
2026-10-01 13:40:27 -07:00

141 lines
5.2 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
/// 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
@safe
public struct TrailingPadding<Header: ~Copyable>: ~Copyable {
/// Pointer to the header, followed by the padding.
@usableFromInline
@unsafe
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")
unsafe _pointer = UnsafeMutableRawPointer
.allocate(byteCount: size, alignment: MemoryLayout<Header>.alignment)
.assumingMemoryBound(to: Header.self)
unsafe _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>) {
unsafe self._pointer = pointer
}
/// Deinitializes the header, then deallocates the underlying memory.
@_alwaysEmitIntoClient
deinit {
unsafe _pointer.deinitialize(count: 1)
unsafe _pointer.deallocate()
}
/// Access the header portion of the value.
@_alwaysEmitIntoClient
public var header: Header {
unsafeAddress {
unsafe UnsafePointer(_pointer)
}
unsafeMutableAddress {
unsafe _pointer
}
}
/// Executes the given closure with the pointer to the header itself.
@_alwaysEmitIntoClient
@unsafe
public func withUnsafeMutablePointerToHeader<R: ~Copyable, E>(
_ body: (UnsafeMutablePointer<Header>) throws(E) -> R
) throws(E) -> R {
return unsafe 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
@unsafe
public consuming func leakStorage() -> UnsafeMutablePointer<Header> {
let pointer = unsafe self._pointer
discard self
return unsafe 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.
return try _withUnsafeTemporaryAllocation(
byteCount: size,
alignment: MemoryLayout<Header>.alignment
) { buffer throws(E) in
/// Create a tail-allocated storage over that temporary storage.
let pointer = unsafe buffer.baseAddress!.assumingMemoryBound(to: Header.self)
unsafe pointer.initialize(to: header)
var tailAllocated: Optional = unsafe TrailingPadding(consuming: pointer)
defer {
let tailAllocated = tailAllocated.take()!
// Tell the tail-allocated buffer not to free the storage.
let finalPointer = unsafe tailAllocated.leakStorage()
precondition(unsafe finalPointer == pointer)
}
return try body(&tailAllocated!)
}
}
}