DocC keeps changing its link syntax. The latest iteration appears to have trouble dealing with `Self`-taking or `Self`-returning methods, so change our API to replace `Self` with a direct mention of the concrete type. ¯\\\_(ツ)\_/¯ That said, the new compiler also found a large number of mismatching parameter names, and that was really helpful.
4.5 KiB
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 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:
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:
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:
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 or MutableSpan over the elements, respectively. Once the coords value is no longer used, the buffer will be deallocated.
print(coords[0]) // displays Point(x: 1, y: 2)
Stack allocation
If heap allocation is not acceptable, use the static method TrailingArray.withTemporaryValue to produce a temporary instance of TrailingArray that can be used within the given body closure, like this:
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 api) using init(consuming:):
init(consuming pointer: UnsafeMutablePointer<Header>)
or give up its pointer to hand off to C with leakStorage:
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, which are described via an incomplete array at the end of a struct. Here is the C equivalent to the Coordinates structure shown above:
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:
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:
var padded = TrailingPadding(header: SomeType(), totalSize: getSizeOfSomeTypeWithPadding())
Topics
Structures
TrailingArrayTrailingPadding
Protocols
TrailingElements