You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Readiness: flip-ready prep for swift-buffer-ring-primitives
- Doc comments on all public declarations; lint conformance (swiftlint
--strict + swift format lint --strict both 0).
- Family E README; per-package .swift-format / metadata backfill where missing.
Floor: clean-room resolve (deps-public verified) + build + test green.
Copy file name to clipboardExpand all lines: .github/metadata.yaml
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,5 @@
1
1
# .github/metadata.yaml
2
-
description: "The ring buffer discipline over the Buffer namespace — circular, count-tracked storage with wrap-around slots and double-ended front/back access, in growable / bounded / inline / small-buffer flavours; supports ~Copyable elements."
2
+
description: "The ring buffer discipline over the Buffer namespace — circular, count-tracked storage with wrap-around slots and double-ended front/back access, in growable and fixed-capacity (bounded) flavours; supports ~Copyable elements."
The **ring buffer discipline** over the `Buffer` namespace: circular, count-tracked storage with
6
-
wrap-around physical slots and double-ended front/back access, in four capacity flavours —
7
-
growable, bounded, inline, and small-buffer-optimized — all supporting noncopyable (`~Copyable`)
8
-
elements.
9
-
10
-
`Buffer.Ring` is one buffer discipline among siblings; linear, slab, linked, slots, and arena
11
-
each live in their own package.
5
+
Circular, count-tracked ring buffers over the `Buffer` namespace — double-ended push/pop/peek with O(1) wrap-around at both ends, in growable and fixed-capacity flavours, over copyable and noncopyable elements.
12
6
13
7
---
14
8
15
9
## Quick Start
16
10
11
+
A ring buffer keeps its elements in a fixed physical window and wraps the head and tail around it, so neither the front nor the back ever shifts elements — both ends are O(1). Two variants ship here: `Buffer.Ring` (growable) and `Buffer.Ring.Bounded` (fixed-capacity).
12
+
17
13
```swift
18
14
importBuffer_Ring_Primitives
19
15
20
-
// Growable, heap-backed ring with double-ended push/pop.
21
-
var ring =Buffer<Int>.Ring(minimumCapacity: 4)
16
+
// These ring buffers pin to heap-backed contiguous storage; alias the spelling once.
// A growable, double-ended FIFO. Both ends are O(1): the head and tail wrap around
20
+
// a fixed physical window, so neither push nor pop shifts the other elements.
21
+
var ring =Buffer<Heap<Int>>.Ring(minimumCapacity: 4)
22
22
ring.push.back(1)
23
23
ring.push.back(2)
24
-
ring.push.front(0)
25
-
let head = ring.peek.front// 0
26
-
_= ring.pop.back() // 2
27
-
28
-
// Small-buffer optimization — inline until it overflows, then spills to the heap.
29
-
var small =Buffer<Int>.Ring.Small<4>()
30
-
for value in1...5 { small.push.back(value) } // the 5th push spills to the heap
31
-
let spilled = small.isSpilled// true
32
-
let front = small.peek.front// 1
24
+
ring.push.front(0) // prepend in O(1)
25
+
let head = ring.peek.front// 0 — read without removing
26
+
let tail = ring.pop.back() // 2 — remove from the back
27
+
```
28
+
29
+
`Buffer.Ring.Bounded` enforces a hard capacity ceiling. A push into a full buffer is *rejected* and handed straight back, so nothing is silently dropped and the buffer never grows:
30
+
31
+
```swift
32
+
importBuffer_Ring_Primitives
33
+
34
+
var window =Buffer<Heap<Int>>.Ring.Bounded(minimumCapacity: 2)
35
+
window.push.back(10)
36
+
window.push.back(20)
37
+
let rejected = window.push.back(30) // Optional(30): the ceiling is reached
38
+
precondition(window.isFull&& rejected ==30)
33
39
```
34
40
35
-
A ring stores elements in a fixed physical window and wraps the head/tail around it, so neither
36
-
front nor back ever shifts elements — both ends are O(1). `Buffer.Ring.Small` keeps short rings
37
-
off the heap entirely and only allocates once they outgrow their inline capacity.
41
+
A ring is also constructible declaratively with a result builder (`Buffer<Heap<Int>>.Ring { 1; 2; 3 }`, where declaration order is the FIFO read order), and drains front-to-back through `drain(_:)` / `removeAll()`. When its element is `Copyable` it conforms to `Sequenceable` for single-pass iteration.
38
42
39
43
---
40
44
@@ -50,48 +54,51 @@ dependencies: [
50
54
.target(
51
55
name: "App",
52
56
dependencies: [
53
-
// The umbrella — the whole package.
57
+
// The umbrella — every variant.
54
58
.product(name: "Buffer Ring Primitives", package: "swift-buffer-ring-primitives"),
55
-
// …or depend on just the variant you use, e.g.:
56
-
// .product(name: "Buffer Ring Small Primitives", package: "swift-buffer-ring-primitives"),
59
+
// …or depend on a single variant, e.g. just the bounded type:
60
+
// .product(name: "Buffer Ring Bounded Primitive", package: "swift-buffer-ring-primitives"),
57
61
]
58
62
)
59
63
```
60
64
61
-
The package is pre-1.0 — depend on `branch: "main"` until `0.1.0` is tagged. Requires Swift 6.3
62
-
and macOS 26 / iOS 26 / tvOS 26 / watchOS 26 / visionOS 26 (or the matching Linux toolchain).
65
+
The package is pre-1.0 — depend on `branch: "main"` until `0.1.0` is tagged.
63
66
64
67
---
65
68
66
-
## Variants
69
+
## Architecture
70
+
71
+
Each variant ships as **two modules**: a lean type module (the `~Copyable` value type plus the operations that touch its storage) and an ops/conformances module (the `Copyable`-requiring `Sequence` conformances, kept separate so they never constrain noncopyable use). The `Buffer Ring Primitives` ops module doubles as the umbrella: it re-exports every variant.
67
72
68
-
| Type | Storage | Reach for it when |
69
-
|------|---------|-------------------|
70
-
|`Buffer.Ring`| heap, growable | the size isn't known up front |
71
-
|`Buffer.Ring.Bounded`| heap, fixed maximum | there is a hard capacity ceiling (push returns the rejected element when full) |
72
-
|`Buffer.Ring.Inline<n>`| inline, fixed | the maximum is small and known at compile time |
|`Buffer Ring Primitives`|`Sources/Buffer Ring Primitives/`| Umbrella + base ops — re-exports every variant; the `Sequenceable` / `Sequence.Drain` conformances, the scalar iterator, and the `.drain` accessor for `Buffer.Ring`. |
76
+
|`Buffer Ring Primitive`|`Sources/Buffer Ring Primitive/`| The lean `Buffer.Ring` type — growable, heap-backed, `~Copyable` — with its push/pop/peek/remove operations, checkpoints, and result builder. |
77
+
|`Buffer Ring Bounded Primitive`|`Sources/Buffer Ring Bounded Primitive/`| The lean `Buffer.Ring.Bounded` type — fixed-capacity, heap-backed, `~Copyable` — whose push returns the rejected element when full. |
78
+
|`Buffer Ring Bounded Primitives`|`Sources/Buffer Ring Bounded Primitives/`| Bounded ops — the `Sequence.Drain` conformance and `.drain` accessor for `Buffer.Ring.Bounded`. |
79
+
|`Buffer Ring Primitives Test Support`|`Tests/Support/`| Re-exports the variant modules for test consumers. |
74
80
75
-
Every variant is generic over `Element`, including noncopyable element types.
81
+
Foundation-free.
76
82
77
83
---
78
84
79
-
## Architecture
85
+
## Platform Support
80
86
81
-
Each variant ships as **two modules**: a lean type module (the value type plus the operations
82
-
that touch its storage) and a conformances module (the `Sequence` conformances, kept separate so
83
-
they never constrain noncopyable use). Importing `Buffer Ring Primitives` brings in the whole
84
-
package; importing a single variant module brings in just that variant.
87
+
| Platform | Status |
88
+
|----------|--------|
89
+
| macOS 26 | Full support |
90
+
| Linux | Full support |
91
+
| Windows | Full support |
92
+
| iOS / tvOS / watchOS / visionOS | Supported |
85
93
86
94
---
87
95
88
-
## Related Packages
96
+
## Community
89
97
90
-
-[`swift-buffer-primitives`](https://github.com/swift-primitives/swift-buffer-primitives) — the `Buffer` namespace and capacity-growth vocabulary.
91
-
-[`swift-storage-primitives`](https://github.com/swift-primitives/swift-storage-primitives) — the heap and inline storage substrate.
92
-
-[`swift-cyclic-index-primitives`](https://github.com/swift-primitives/swift-cyclic-index-primitives) — the modular (wrap-around) index arithmetic.
0 commit comments