mirror of
https://github.com/apple/swift-collections
synced 2026-11-22 04:20:40 +00:00
116 lines
4.5 KiB
Markdown
116 lines
4.5 KiB
Markdown
# ``TrailingElementsModule``
|
|
|
|
## Overview
|
|
|
|
This module provides types that manage values consisting of a fixed-size header
|
|
plus variable-size storage that follows that header in memory. The types are
|
|
similar in design to the [`ManagedBuffer`](https://developer.apple.com/documentation/swift/managedbuffer) type in the standard library, but are non-copyable types that eliminate the need for reference counting and heap allocation.
|
|
|
|
|
|
The ``TrailingArray`` type can be used for types consisting of a header after which there are some (dynamic) number of elements. For example, we could have a `Coordinates` type that is followed by `Point` elements:
|
|
|
|
```swift
|
|
struct Point {
|
|
var x: Int
|
|
var y: Int
|
|
}
|
|
|
|
struct Coordinates {
|
|
var numPoints: Int
|
|
// Points will follow in memory
|
|
}
|
|
```
|
|
|
|
To use ``TrailingArray``, the `Coordinates` type must conform to the
|
|
``TrailingElements`` protocol, specifying the type of the trailing elements (`Point`) and the number of trailing elements (`numPoints`), like this:
|
|
|
|
```swift
|
|
extension Coordinates: TrailingElements {
|
|
typealias Element = Point
|
|
var trailingCount: Int { numPoints }
|
|
}
|
|
```
|
|
|
|
Now, we can create an intrusive managed buffer. The easiest way is to do so on the heap:
|
|
|
|
```swift
|
|
var coords = TrailingArray(header: Coordinates(numPoints: 3)) { outputSpan in
|
|
outputSpan.append(Point(x: 1, y: 2))
|
|
outputSpan.append(Point(x: 2, y: 3))
|
|
outputSpan.append(Point(x: 3, y: 4))
|
|
}
|
|
```
|
|
|
|
Subscripting an ``TrailingArray`` provides access to the elements. One can also use the ``TrailingArray/elements`` or ``TrailingArray/mutableElements`` properties to get a [`Span`](https://developer.apple.com/documentation/swift/span) or [`MutableSpan`](https://developer.apple.com/documentation/swift/mutablespan) over the elements, respectively. Once the `coords` value is no longer used, the buffer will be deallocated.
|
|
|
|
```swift
|
|
print(coords[0]) // displays Point(x: 1, y: 2)
|
|
```
|
|
|
|
### Stack allocation
|
|
If heap allocation is not acceptable, use the static method ``TrailingArray/withTemporaryValue(header:repeating:body:)`` to produce a temporary instance of ``TrailingArray`` that can be used within the given body closure, like this:
|
|
|
|
```swift
|
|
TrailingArray.withTemporaryValue(header: Coordinates(numPoints: 3), repeating: Point(x: 0, y: 0)) { coords in
|
|
coords[0] = Point(x: 1, y: 2)
|
|
coords[1] = Point(x: 2, y: 3)
|
|
coords[2] = Point(x: 3, y: 4)
|
|
|
|
// operate on coords
|
|
}
|
|
```
|
|
|
|
### Interoperability with unsafe C APIs
|
|
``TrailingArray`` provides facilities for working with the underlying unsafe pointers, which can be useful when interoperating with C APIs. ``TrailingArray`` can take ownership of a heap-allocated pointer to its `Header` type (such as one might get back from a C API) using `init(consuming:)`:
|
|
|
|
```swift
|
|
init(consuming pointer: UnsafeMutablePointer<Header>)
|
|
```
|
|
|
|
or give up its pointer to hand off to C with `leakStorage`:
|
|
|
|
```swift
|
|
consuming func leakStorage() -> UnsafeMutablePointer<Header>
|
|
```
|
|
|
|
Unsafe pointers can be accessed via the `withUnsafeMutablePointer*` family of methods to access a pointer to the header, the trailing elements, or both.
|
|
|
|
### Flexible array members
|
|
One of the uses for this module is to work with C types that involve [flexible array members](https://en.wikipedia.org/wiki/Flexible_array_member), which are described via an incomplete array at the end of a struct. Here is the C equivalent to the `Coordinates` structure shown above:
|
|
|
|
```c
|
|
struct coordinates_t {
|
|
unsigned num_points;
|
|
struct point_t points[];
|
|
};
|
|
```
|
|
|
|
The C `coordinates_t` type can extended to conform to the ``TrailingElements`` protocol, allowing it to be used directly with ``TrailingArray``:
|
|
|
|
```swift
|
|
extension coordinates_t: TrailingElements {
|
|
typealias Element = point_t
|
|
var trailingCount: Int { num_points }
|
|
}
|
|
```
|
|
|
|
This provides safer access patterns for C flexible array members, introducing safe memory ownership and bounds-safety checking.
|
|
|
|
### ``TrailingPadding``
|
|
|
|
This module also provides a lower-level primitive called ``TrailingPadding`` that references heap- or stack-allocated data with a particular type (also called the `Header` type) but whose allocation is larger than the size of the header itself. The API is roughly similar to that of ``TrailingArray``, but it has no notion of what data might follow the `Header` instance. Instead, its initializer takes a "total size" for the allocation size, leaving the size calculation to the user:
|
|
|
|
```swift
|
|
var padded = TrailingPadding(header: SomeType(), totalSize: getSizeOfSomeTypeWithPadding())
|
|
```
|
|
|
|
## Topics
|
|
|
|
### Structures
|
|
|
|
- ``TrailingArray``
|
|
- ``TrailingPadding``
|
|
|
|
### Protocols
|
|
- ``TrailingElements``
|