| ... | ... | @@ -1,8 +1,8 @@ |
| 1 | 1 | //! This ring buffer stores read and write indices while being able to utilise the full |
| 2 | 2 | //! backing slice by incrementing the indices modulo twice the slice's length and reducing |
| 3 | | //! indices modulo the slice's length on slice access. This means that the bit of information |
| 4 | | //! distinguishing whether the buffer is full or empty in an implementation utilising |
| 5 | | //! and extra flag is stored in difference of the indices. |
| 3 | //! indices modulo the slice's length on slice access. This means that whether the ring buffer |
| 4 | //! if full or empty can be distinguised by looking at the different between the read and write |
| 5 | //! indices without adding an extra boolean flag or having to reserve a slot in the buffer. |
| 6 | 6 | |
| 7 | 7 | const assert = @import("std").debug.assert; |
| 8 | 8 | |
| ... | ... | @@ -12,33 +12,45 @@ data: []u8, |
| 12 | 12 | read_index: usize, |
| 13 | 13 | write_index: usize, |
| 14 | 14 | |
| 15 | /// Returns `index` modulo the length of the backing slice. |
| 15 | 16 | pub fn mask(self: RingBuffer, index: usize) usize { |
| 16 | 17 | return index % self.data.len; |
| 17 | 18 | } |
| 18 | 19 | |
| 20 | /// Returns `index` module twice the length of the backing slice. |
| 19 | 21 | pub fn mask2(self: RingBuffer, index: usize) usize { |
| 20 | 22 | return index % (2 * self.data.len); |
| 21 | 23 | } |
| 22 | 24 | |
| 25 | /// Write `byte` into the ring buffer. Returns `error.Full` if the ring |
| 26 | /// buffer is full. |
| 23 | 27 | pub fn write(self: *RingBuffer, byte: u8) !void { |
| 24 | 28 | if (self.isFull()) return error.Full; |
| 25 | 29 | self.writeAssumeCapacity(byte); |
| 26 | 30 | } |
| 27 | 31 | |
| 32 | /// Write `byte` into the ring buffer. If the ring buffer is full, the |
| 33 | /// oldest byte is overwritten. |
| 28 | 34 | pub fn writeAssumeCapacity(self: *RingBuffer, byte: u8) void { |
| 29 | 35 | self.data[self.mask(self.write_index)] = byte; |
| 30 | 36 | self.write_index = self.mask2(self.write_index + 1); |
| 31 | 37 | } |
| 32 | 38 | |
| 39 | /// Write `bytes` into the ring bufffer. Returns `error.Full` if the ring |
| 40 | /// buffer does not have enough space, without writing any data. |
| 33 | 41 | pub fn writeSlice(self: *RingBuffer, bytes: []const u8) !void { |
| 34 | 42 | if (self.len() + bytes.len > self.data.len) return error.Full; |
| 35 | 43 | self.writeSliceAssumeCapacity(bytes); |
| 36 | 44 | } |
| 37 | 45 | |
| 46 | /// Write `bytes` into the ring buffer. If there is not enough space, older |
| 47 | /// bytes will be overwritten. |
| 38 | 48 | pub fn writeSliceAssumeCapacity(self: *RingBuffer, bytes: []const u8) void { |
| 39 | 49 | for (bytes) |b| self.writeAssumeCapacity(b); |
| 40 | 50 | } |
| 41 | 51 | |
| 52 | /// Consume a byte from the ring buffer and return it. Returns `null` if the |
| 53 | /// ring buffer is empty. |
| 42 | 54 | pub fn read(self: *RingBuffer) ?u8 { |
| 43 | 55 | if (self.isEmpty()) return null; |
| 44 | 56 | const byte = self.data[self.mask(self.read_index)]; |
| ... | ... | @@ -46,24 +58,32 @@ pub fn read(self: *RingBuffer) ?u8 { |
| 46 | 58 | return byte; |
| 47 | 59 | } |
| 48 | 60 | |
| 61 | /// Returns `true` if the ring buffer is empty and `false` otherwise. |
| 49 | 62 | pub fn isEmpty(self: RingBuffer) bool { |
| 50 | 63 | return self.write_index == self.read_index; |
| 51 | 64 | } |
| 52 | 65 | |
| 66 | /// Returns `true` if the ring buffer is full and `false` otherwise. |
| 53 | 67 | pub fn isFull(self: RingBuffer) bool { |
| 54 | 68 | return self.mask2(self.write_index + self.data.len) == self.read_index; |
| 55 | 69 | } |
| 56 | 70 | |
| 71 | /// Returns the length |
| 57 | 72 | pub fn len(self: RingBuffer) usize { |
| 58 | 73 | const adjusted_write_index = self.write_index + @boolToInt(self.write_index < self.read_index) * 2 * self.data.len; |
| 59 | 74 | return adjusted_write_index - self.read_index; |
| 60 | 75 | } |
| 61 | 76 | |
| 62 | | const Slice = struct { |
| 77 | /// A `Slice` represents a region of a ring buffer. The region is split into two |
| 78 | /// sections as the ring buffer data will not be contiguous if the desired region |
| 79 | /// wraps to the start of the backing slice. |
| 80 | pub const Slice = struct { |
| 63 | 81 | first: []u8, |
| 64 | 82 | second: []u8, |
| 65 | 83 | }; |
| 66 | 84 | |
| 85 | /// Returns a `Slice` for the region of the ring buffer staring at `self.mask(start_unmasked)` |
| 86 | /// with the specified length. |
| 67 | 87 | pub fn sliceAt(self: RingBuffer, start_unmasked: usize, length: usize) Slice { |
| 68 | 88 | assert(length <= self.data.len); |
| 69 | 89 | const slice1_start = self.mask(start_unmasked); |
| ... | ... | @@ -76,6 +96,7 @@ pub fn sliceAt(self: RingBuffer, start_unmasked: usize, length: usize) Slice { |
| 76 | 96 | }; |
| 77 | 97 | } |
| 78 | 98 | |
| 99 | /// Returns a `Slice` for the last `length` bytes written to the ring buffer. |
| 79 | 100 | pub fn sliceLast(self: RingBuffer, length: usize) Slice { |
| 80 | 101 | return self.sliceAt(self.write_index + self.data.len - length, length); |
| 81 | 102 | } |
Dominic <4678790+dweiller@users.noreply.github.com> 2023-01-27 23:50:23+11:00
lib