| ... | ... | @@ -1,230 +0,0 @@ |
| 1 | | //! This ring buffer stores read and write indices while being able to utilise |
| 2 | | //! the full backing slice by incrementing the indices modulo twice the slice's |
| 3 | | //! length and reducing indices modulo the slice's length on slice access. This |
| 4 | | //! means that whether the ring buffer is full or empty can be distinguished by |
| 5 | | //! looking at the difference between the read and write indices without adding |
| 6 | | //! an extra boolean flag or having to reserve a slot in the buffer. |
| 7 | | //! |
| 8 | | //! This ring buffer has not been implemented with thread safety in mind, and |
| 9 | | //! therefore should not be assumed to be suitable for use cases involving |
| 10 | | //! separate reader and writer threads. |
| 11 | | |
| 12 | | const Allocator = @import("std").mem.Allocator; |
| 13 | | const assert = @import("std").debug.assert; |
| 14 | | const copyForwards = @import("std").mem.copyForwards; |
| 15 | | |
| 16 | | const RingBuffer = @This(); |
| 17 | | |
| 18 | | data: []u8, |
| 19 | | read_index: usize, |
| 20 | | write_index: usize, |
| 21 | | |
| 22 | | pub const Error = error{ Full, ReadLengthInvalid }; |
| 23 | | |
| 24 | | /// Allocate a new `RingBuffer`; `deinit()` should be called to free the buffer. |
| 25 | | pub fn init(allocator: Allocator, capacity: usize) Allocator.Error!RingBuffer { |
| 26 | | const bytes = try allocator.alloc(u8, capacity); |
| 27 | | return RingBuffer{ |
| 28 | | .data = bytes, |
| 29 | | .write_index = 0, |
| 30 | | .read_index = 0, |
| 31 | | }; |
| 32 | | } |
| 33 | | |
| 34 | | /// Free the data backing a `RingBuffer`; must be passed the same `Allocator` as |
| 35 | | /// `init()`. |
| 36 | | pub fn deinit(self: *RingBuffer, allocator: Allocator) void { |
| 37 | | allocator.free(self.data); |
| 38 | | self.* = undefined; |
| 39 | | } |
| 40 | | |
| 41 | | /// Returns `index` modulo the length of the backing slice. |
| 42 | | pub fn mask(self: RingBuffer, index: usize) usize { |
| 43 | | return index % self.data.len; |
| 44 | | } |
| 45 | | |
| 46 | | /// Returns `index` modulo twice the length of the backing slice. |
| 47 | | pub fn mask2(self: RingBuffer, index: usize) usize { |
| 48 | | return index % (2 * self.data.len); |
| 49 | | } |
| 50 | | |
| 51 | | /// Write `byte` into the ring buffer. Returns `error.Full` if the ring |
| 52 | | /// buffer is full. |
| 53 | | pub fn write(self: *RingBuffer, byte: u8) Error!void { |
| 54 | | if (self.isFull()) return error.Full; |
| 55 | | self.writeAssumeCapacity(byte); |
| 56 | | } |
| 57 | | |
| 58 | | /// Write `byte` into the ring buffer. If the ring buffer is full, the |
| 59 | | /// oldest byte is overwritten. |
| 60 | | pub fn writeAssumeCapacity(self: *RingBuffer, byte: u8) void { |
| 61 | | self.data[self.mask(self.write_index)] = byte; |
| 62 | | self.write_index = self.mask2(self.write_index + 1); |
| 63 | | } |
| 64 | | |
| 65 | | /// Write `bytes` into the ring buffer. Returns `error.Full` if the ring |
| 66 | | /// buffer does not have enough space, without writing any data. |
| 67 | | /// Uses memcpy and so `bytes` must not overlap ring buffer data. |
| 68 | | pub fn writeSlice(self: *RingBuffer, bytes: []const u8) Error!void { |
| 69 | | if (self.len() + bytes.len > self.data.len) return error.Full; |
| 70 | | self.writeSliceAssumeCapacity(bytes); |
| 71 | | } |
| 72 | | |
| 73 | | /// Write `bytes` into the ring buffer. If there is not enough space, older |
| 74 | | /// bytes will be overwritten. |
| 75 | | /// Uses memcpy and so `bytes` must not overlap ring buffer data. |
| 76 | | pub fn writeSliceAssumeCapacity(self: *RingBuffer, bytes: []const u8) void { |
| 77 | | assert(bytes.len <= self.data.len); |
| 78 | | const data_start = self.mask(self.write_index); |
| 79 | | const part1_data_end = @min(data_start + bytes.len, self.data.len); |
| 80 | | const part1_len = part1_data_end - data_start; |
| 81 | | @memcpy(self.data[data_start..part1_data_end], bytes[0..part1_len]); |
| 82 | | |
| 83 | | const remaining = bytes.len - part1_len; |
| 84 | | const to_write = @min(remaining, remaining % self.data.len + self.data.len); |
| 85 | | const part2_bytes_start = bytes.len - to_write; |
| 86 | | const part2_bytes_end = @min(part2_bytes_start + self.data.len, bytes.len); |
| 87 | | const part2_len = part2_bytes_end - part2_bytes_start; |
| 88 | | @memcpy(self.data[0..part2_len], bytes[part2_bytes_start..part2_bytes_end]); |
| 89 | | if (part2_bytes_end != bytes.len) { |
| 90 | | const part3_len = bytes.len - part2_bytes_end; |
| 91 | | @memcpy(self.data[0..part3_len], bytes[part2_bytes_end..bytes.len]); |
| 92 | | } |
| 93 | | self.write_index = self.mask2(self.write_index + bytes.len); |
| 94 | | } |
| 95 | | |
| 96 | | /// Write `bytes` into the ring buffer. Returns `error.Full` if the ring |
| 97 | | /// buffer does not have enough space, without writing any data. |
| 98 | | /// Uses copyForwards and can write slices from this RingBuffer into itself. |
| 99 | | pub fn writeSliceForwards(self: *RingBuffer, bytes: []const u8) Error!void { |
| 100 | | if (self.len() + bytes.len > self.data.len) return error.Full; |
| 101 | | self.writeSliceForwardsAssumeCapacity(bytes); |
| 102 | | } |
| 103 | | |
| 104 | | /// Write `bytes` into the ring buffer. If there is not enough space, older |
| 105 | | /// bytes will be overwritten. |
| 106 | | /// Uses copyForwards and can write slices from this RingBuffer into itself. |
| 107 | | pub fn writeSliceForwardsAssumeCapacity(self: *RingBuffer, bytes: []const u8) void { |
| 108 | | assert(bytes.len <= self.data.len); |
| 109 | | const data_start = self.mask(self.write_index); |
| 110 | | const part1_data_end = @min(data_start + bytes.len, self.data.len); |
| 111 | | const part1_len = part1_data_end - data_start; |
| 112 | | copyForwards(u8, self.data[data_start..], bytes[0..part1_len]); |
| 113 | | |
| 114 | | const remaining = bytes.len - part1_len; |
| 115 | | const to_write = @min(remaining, remaining % self.data.len + self.data.len); |
| 116 | | const part2_bytes_start = bytes.len - to_write; |
| 117 | | const part2_bytes_end = @min(part2_bytes_start + self.data.len, bytes.len); |
| 118 | | copyForwards(u8, self.data[0..], bytes[part2_bytes_start..part2_bytes_end]); |
| 119 | | if (part2_bytes_end != bytes.len) |
| 120 | | copyForwards(u8, self.data[0..], bytes[part2_bytes_end..bytes.len]); |
| 121 | | self.write_index = self.mask2(self.write_index + bytes.len); |
| 122 | | } |
| 123 | | |
| 124 | | /// Consume a byte from the ring buffer and return it. Returns `null` if the |
| 125 | | /// ring buffer is empty. |
| 126 | | pub fn read(self: *RingBuffer) ?u8 { |
| 127 | | if (self.isEmpty()) return null; |
| 128 | | return self.readAssumeLength(); |
| 129 | | } |
| 130 | | |
| 131 | | /// Consume a byte from the ring buffer and return it; asserts that the buffer |
| 132 | | /// is not empty. |
| 133 | | pub fn readAssumeLength(self: *RingBuffer) u8 { |
| 134 | | assert(!self.isEmpty()); |
| 135 | | const byte = self.data[self.mask(self.read_index)]; |
| 136 | | self.read_index = self.mask2(self.read_index + 1); |
| 137 | | return byte; |
| 138 | | } |
| 139 | | |
| 140 | | /// Reads first `length` bytes written to the ring buffer into `dest`; Returns |
| 141 | | /// Error.ReadLengthInvalid if length greater than ring or dest length |
| 142 | | /// Uses memcpy and so `dest` must not overlap ring buffer data. |
| 143 | | pub fn readFirst(self: *RingBuffer, dest: []u8, length: usize) Error!void { |
| 144 | | if (length > self.len() or length > dest.len) return error.ReadLengthInvalid; |
| 145 | | self.readFirstAssumeLength(dest, length); |
| 146 | | } |
| 147 | | |
| 148 | | /// Reads first `length` bytes written to the ring buffer into `dest`; |
| 149 | | /// Asserts that length not greater than ring buffer or dest length |
| 150 | | /// Uses memcpy and so `dest` must not overlap ring buffer data. |
| 151 | | pub fn readFirstAssumeLength(self: *RingBuffer, dest: []u8, length: usize) void { |
| 152 | | assert(length <= self.len() and length <= dest.len); |
| 153 | | const slice = self.sliceAt(self.read_index, length); |
| 154 | | slice.copyTo(dest); |
| 155 | | self.read_index = self.mask2(self.read_index + length); |
| 156 | | } |
| 157 | | |
| 158 | | /// Reads last `length` bytes written to the ring buffer into `dest`; Returns |
| 159 | | /// Error.ReadLengthInvalid if length greater than ring or dest length |
| 160 | | /// Uses memcpy and so `dest` must not overlap ring buffer data. |
| 161 | | /// Reduces write index by `length`. |
| 162 | | pub fn readLast(self: *RingBuffer, dest: []u8, length: usize) Error!void { |
| 163 | | if (length > self.len() or length > dest.len) return error.ReadLengthInvalid; |
| 164 | | self.readLastAssumeLength(dest, length); |
| 165 | | } |
| 166 | | |
| 167 | | /// Reads last `length` bytes written to the ring buffer into `dest`; |
| 168 | | /// Asserts that length not greater than ring buffer or dest length |
| 169 | | /// Uses memcpy and so `dest` must not overlap ring buffer data. |
| 170 | | /// Reduces write index by `length`. |
| 171 | | pub fn readLastAssumeLength(self: *RingBuffer, dest: []u8, length: usize) void { |
| 172 | | assert(length <= self.len() and length <= dest.len); |
| 173 | | const slice = self.sliceLast(length); |
| 174 | | slice.copyTo(dest); |
| 175 | | self.write_index = if (self.write_index >= self.data.len) |
| 176 | | self.write_index - length |
| 177 | | else |
| 178 | | self.mask(self.write_index + self.data.len - length); |
| 179 | | } |
| 180 | | |
| 181 | | /// Returns `true` if the ring buffer is empty and `false` otherwise. |
| 182 | | pub fn isEmpty(self: RingBuffer) bool { |
| 183 | | return self.write_index == self.read_index; |
| 184 | | } |
| 185 | | |
| 186 | | /// Returns `true` if the ring buffer is full and `false` otherwise. |
| 187 | | pub fn isFull(self: RingBuffer) bool { |
| 188 | | return self.mask2(self.write_index + self.data.len) == self.read_index; |
| 189 | | } |
| 190 | | |
| 191 | | /// Returns the length of data available for reading |
| 192 | | pub fn len(self: RingBuffer) usize { |
| 193 | | const wrap_offset = 2 * self.data.len * @intFromBool(self.write_index < self.read_index); |
| 194 | | const adjusted_write_index = self.write_index + wrap_offset; |
| 195 | | return adjusted_write_index - self.read_index; |
| 196 | | } |
| 197 | | |
| 198 | | /// A `Slice` represents a region of a ring buffer. The region is split into two |
| 199 | | /// sections as the ring buffer data will not be contiguous if the desired |
| 200 | | /// region wraps to the start of the backing slice. |
| 201 | | pub const Slice = struct { |
| 202 | | first: []u8, |
| 203 | | second: []u8, |
| 204 | | |
| 205 | | /// Copy data from `self` into `dest` |
| 206 | | pub fn copyTo(self: Slice, dest: []u8) void { |
| 207 | | @memcpy(dest[0..self.first.len], self.first); |
| 208 | | @memcpy(dest[self.first.len..][0..self.second.len], self.second); |
| 209 | | } |
| 210 | | }; |
| 211 | | |
| 212 | | /// Returns a `Slice` for the region of the ring buffer starting at |
| 213 | | /// `self.mask(start_unmasked)` with the specified length. |
| 214 | | pub fn sliceAt(self: RingBuffer, start_unmasked: usize, length: usize) Slice { |
| 215 | | assert(length <= self.data.len); |
| 216 | | const slice1_start = self.mask(start_unmasked); |
| 217 | | const slice1_end = @min(self.data.len, slice1_start + length); |
| 218 | | const slice1 = self.data[slice1_start..slice1_end]; |
| 219 | | const slice2 = self.data[0 .. length - slice1.len]; |
| 220 | | return Slice{ |
| 221 | | .first = slice1, |
| 222 | | .second = slice2, |
| 223 | | }; |
| 224 | | } |
| 225 | | |
| 226 | | /// Returns a `Slice` for the last `length` bytes written to the ring buffer. |
| 227 | | /// Does not check that any bytes have been written into the region. |
| 228 | | pub fn sliceLast(self: RingBuffer, length: usize) Slice { |
| 229 | | return self.sliceAt(self.write_index + self.data.len - length, length); |
| 230 | | } |
Andrew Kelley <andrew@ziglang.org> 2025-08-04 23:59:48-07:00
lib