diff --git a/lib/std/compress/zstandard/RingBuffer.zig b/lib/std/RingBuffer.zig similarity index 72% rename from lib/std/compress/zstandard/RingBuffer.zig rename to lib/std/RingBuffer.zig index 5bd7e5d1f9..857775b5a0 100644 --- a/lib/std/compress/zstandard/RingBuffer.zig +++ b/lib/std/RingBuffer.zig @@ -1,8 +1,13 @@ -//! This ring buffer stores read and write indices while being able to utilise the full -//! backing slice by incrementing the indices modulo twice the slice's length and reducing -//! indices modulo the slice's length on slice access. This means that whether the ring buffer -//! if full or empty can be distinguised by looking at the different between the read and write -//! indices without adding an extra boolean flag or having to reserve a slot in the buffer. +//! This ring buffer stores read and write indices while being able to utilise +//! the full backing slice by incrementing the indices modulo twice the slice's +//! length and reducing indices modulo the slice's length on slice access. This +//! means that whether the ring buffer if full or empty can be distinguished by +//! looking at the difference between the read and write indices without adding +//! an extra boolean flag or having to reserve a slot in the buffer. +//! +//! This ring buffer has not been implemented with thread safety in mind, and +//! therefore should not be assumed to be suitable for use cases involving +//! separate reader and writer threads. const Allocator = @import("std").mem.Allocator; const assert = @import("std").debug.assert; @@ -15,7 +20,7 @@ write_index: usize, pub const Error = error{Full}; -/// Allocate a new `RingBuffer` +/// Allocate a new `RingBuffer`; `deinit()` should be called to free the buffer. pub fn init(allocator: Allocator, capacity: usize) Allocator.Error!RingBuffer { const bytes = try allocator.alloc(u8, capacity); return RingBuffer{ @@ -25,7 +30,8 @@ pub fn init(allocator: Allocator, capacity: usize) Allocator.Error!RingBuffer { }; } -/// Free a `RingBuffer` +/// Free the data backing a `RingBuffer`; must be passed the same `Allocator` as +/// `init()`. pub fn deinit(self: *RingBuffer, allocator: Allocator) void { allocator.free(self.data); self.* = undefined; @@ -36,7 +42,7 @@ pub fn mask(self: RingBuffer, index: usize) usize { return index % self.data.len; } -/// Returns `index` module twice the length of the backing slice. +/// Returns `index` modulo twice the length of the backing slice. pub fn mask2(self: RingBuffer, index: usize) usize { return index % (2 * self.data.len); } @@ -55,7 +61,7 @@ pub fn writeAssumeCapacity(self: *RingBuffer, byte: u8) void { self.write_index = self.mask2(self.write_index + 1); } -/// Write `bytes` into the ring bufffer. Returns `error.Full` if the ring +/// Write `bytes` into the ring buffer. Returns `error.Full` if the ring /// buffer does not have enough space, without writing any data. pub fn writeSlice(self: *RingBuffer, bytes: []const u8) Error!void { if (self.len() + bytes.len > self.data.len) return error.Full; @@ -72,6 +78,13 @@ pub fn writeSliceAssumeCapacity(self: *RingBuffer, bytes: []const u8) void { /// ring buffer is empty. pub fn read(self: *RingBuffer) ?u8 { if (self.isEmpty()) return null; + return self.readAssumeLength(); +} + +/// Consume a byte from the ring buffer and return it; asserts that the buffer +/// is not empty. +pub fn readAssumeLength(self: *RingBuffer) u8 { + assert(!self.isEmpty()); const byte = self.data[self.mask(self.read_index)]; self.read_index = self.mask2(self.read_index + 1); return byte; @@ -95,15 +108,15 @@ pub fn len(self: RingBuffer) usize { } /// A `Slice` represents a region of a ring buffer. The region is split into two -/// sections as the ring buffer data will not be contiguous if the desired region -/// wraps to the start of the backing slice. +/// sections as the ring buffer data will not be contiguous if the desired +/// region wraps to the start of the backing slice. pub const Slice = struct { first: []u8, second: []u8, }; -/// Returns a `Slice` for the region of the ring buffer staring at `self.mask(start_unmasked)` -/// with the specified length. +/// Returns a `Slice` for the region of the ring buffer starting at +/// `self.mask(start_unmasked)` with the specified length. pub fn sliceAt(self: RingBuffer, start_unmasked: usize, length: usize) Slice { assert(length <= self.data.len); const slice1_start = self.mask(start_unmasked); @@ -117,6 +130,7 @@ pub fn sliceAt(self: RingBuffer, start_unmasked: usize, length: usize) Slice { } /// Returns a `Slice` for the last `length` bytes written to the ring buffer. +/// Does not check that any bytes have been written into the region. pub fn sliceLast(self: RingBuffer, length: usize) Slice { return self.sliceAt(self.write_index + self.data.len - length, length); } diff --git a/lib/std/compress/zstandard.zig b/lib/std/compress/zstandard.zig index 5f61c4dc30..fcffed99f1 100644 --- a/lib/std/compress/zstandard.zig +++ b/lib/std/compress/zstandard.zig @@ -1,11 +1,11 @@ const std = @import("std"); const Allocator = std.mem.Allocator; +const RingBuffer = std.RingBuffer; const types = @import("zstandard/types.zig"); pub const frame = types.frame; pub const compressed_block = types.compressed_block; -const RingBuffer = @import("zstandard/RingBuffer.zig"); pub const decompress = @import("zstandard/decompress.zig"); pub fn DecompressStream( diff --git a/lib/std/compress/zstandard/decode/block.zig b/lib/std/compress/zstandard/decode/block.zig index ba8e8d998c..4b7353f63c 100644 --- a/lib/std/compress/zstandard/decode/block.zig +++ b/lib/std/compress/zstandard/decode/block.zig @@ -1,5 +1,6 @@ const std = @import("std"); const assert = std.debug.assert; +const RingBuffer = std.RingBuffer; const types = @import("../types.zig"); const frame = types.frame; @@ -8,9 +9,6 @@ const LiteralsSection = types.compressed_block.LiteralsSection; const SequencesSection = types.compressed_block.SequencesSection; const huffman = @import("huffman.zig"); - -const RingBuffer = @import("../RingBuffer.zig"); - const readers = @import("../readers.zig"); const decodeFseTable = @import("fse.zig").decodeFseTable; diff --git a/lib/std/compress/zstandard/decompress.zig b/lib/std/compress/zstandard/decompress.zig index 31c5660642..ffa01b94f1 100644 --- a/lib/std/compress/zstandard/decompress.zig +++ b/lib/std/compress/zstandard/decompress.zig @@ -1,6 +1,7 @@ const std = @import("std"); const assert = std.debug.assert; const Allocator = std.mem.Allocator; +const RingBuffer = std.RingBuffer; const types = @import("types.zig"); const frame = types.frame; @@ -12,8 +13,6 @@ const Table = types.compressed_block.Table; pub const block = @import("decode/block.zig"); -pub const RingBuffer = @import("RingBuffer.zig"); - const readers = @import("readers.zig"); const readInt = std.mem.readIntLittle; diff --git a/lib/std/std.zig b/lib/std/std.zig index 5b0963ba20..4a6d330003 100644 --- a/lib/std/std.zig +++ b/lib/std/std.zig @@ -31,6 +31,7 @@ pub const PackedIntSliceEndian = @import("packed_int_array.zig").PackedIntSliceE pub const PriorityQueue = @import("priority_queue.zig").PriorityQueue; pub const PriorityDequeue = @import("priority_dequeue.zig").PriorityDequeue; pub const Progress = @import("Progress.zig"); +pub const RingBuffer = @import("RingBuffer.zig"); pub const SegmentedList = @import("segmented_list.zig").SegmentedList; pub const SemanticVersion = @import("SemanticVersion.zig"); pub const SinglyLinkedList = @import("linked_list.zig").SinglyLinkedList;