ringbuf2: Replacement for ringbuf.

I found the ringbuf somewhat clunky and hard to use.  Replace it by a
lighter weight, non-macro based ring buffer with a more useful API.

Author: lorinder

src/csnip/CMakeLists.txt

@@ -121,6 +121,7 @@ set(public_headers
 	podtypes.h
 	preproc.h
 	ringbuf.h
+	ringbuf2.h
 	rng.h
 	rng_mt.h
 	runif.h
@@ -137,6 +138,7 @@ set(c_sources
 	log.c
 	meanvar.c
 	mem.c
+	ringbuf2.c
 	rng.c
 	rng_mt.c
 	runif.c

src/csnip/ringbuf2.c

@@ -0,0 +1,75 @@
+#include <assert.h>
+
+#define CSNIP_SHORT_NAMES
+#include <csnip/util.h>
+#include <csnip/ringbuf2.h>
+
+size_t ringbuf2_init(ringbuf2* rb, size_t min_cap)
+{
+	/* The actual capacity must be a power of 2 (for otherwise, a
+	 * wrap in the n_written or n_read indices would corrupt the
+	 * write/read position index.)
+	 *
+	 * We pick the next larger power of 2.
+	 */
+	const size_t cap = next_pow_of_2(min_cap);
+
+	*rb = (ringbuf2) {
+		.cap = cap,
+		.n_written = 0,
+		.n_read = 0
+	};
+
+	return cap;
+}
+
+ringbuf2 ringbuf2_make(size_t min_cap)
+{
+	ringbuf2 rb;
+	ringbuf2_init(&rb, min_cap);
+	return rb;
+}
+
+size_t ringbuf2_used_size(const ringbuf2* rb)
+{
+	return rb->n_written - rb->n_read;
+}
+
+size_t ringbuf2_free_size(const ringbuf2* rb)
+{
+	return rb->cap - ringbuf2_used_size(rb);
+}
+
+size_t ringbuf2_get_write_idx(const ringbuf2* rb, size_t* ret_contig_write_max)
+{
+	const size_t write_idx = rb->n_written & (rb->cap - 1);
+	if (ret_contig_write_max) {
+		const size_t n_free = ringbuf2_free_size(rb);
+		const size_t n_to_end = rb->cap - write_idx;
+		*ret_contig_write_max = Min(n_free, n_to_end);
+	}
+	return write_idx;
+}
+
+bool ringbuf2_add_written(ringbuf2* rb, size_t n_written)
+{
+	rb->n_written += n_written;
+	return rb->n_written - rb->n_read <= rb->cap;
+}
+
+size_t ringbuf2_get_read_idx(const ringbuf2* rb, size_t* ret_contig_read_max)
+{
+	const size_t read_idx = rb->n_read & (rb->cap - 1);
+	if (ret_contig_read_max) {
+		const size_t n_used = ringbuf2_used_size(rb);
+		const size_t n_to_end = rb->cap - read_idx;
+		*ret_contig_read_max = Min(n_used, n_to_end);
+	}
+	return read_idx;
+}
+
+bool ringbuf2_add_read(ringbuf2* rb, size_t n_read)
+{
+	rb->n_read += n_read;
+	return rb->n_read <= rb->n_written;
+}

src/csnip/ringbuf2.h

@@ -0,0 +1,79 @@
+#ifndef CSNIP_RINGBUF2_H
+#define CSNIP_RINGBUF2_H
+
+/**	@file ringbuf2.h
+ *	@brief				Ring buffers, v2
+ *	@defgroup ringbuf2		Ring buffers, v2
+ *	@{
+ *
+ *	@brief Ring buffer implementation, v2
+ *
+ *	Implements a simple ring buffer with a capacity of a power of 2.
+ *	This module only manages the indices, the user needs to keep a
+ *	backing array separately.
+ *
+ *	This module is intended as a replacement for csnip's first
+ *	ringbuf module;  the former has been found to be clunky to use
+ *	in practice.
+ *
+ *	No type generic macros are provided here, as the data structure
+ *	has a fixed type.
+ *
+ *	The data structure used here, making use of controlled unsigned
+ *	integer overflow is inspired by io_uring's communication ring
+ *	buffers, see https://kernel.dk/io_uring.pdf
+ */
+
+#include <stdbool.h>
+#include <stddef.h>
+
+typedef struct {
+	/** buffer capacity.
+	 *
+	 *  Must be a power of 2.
+	 */
+	size_t cap;
+
+	/** Number of elements written so far.
+	 *
+	 *  The number is mod (SIZE_MAX + 1), i.e., using C's
+	 *  wrapping unsigned integer arithmetic.
+	 */
+	size_t n_written;
+
+	/** Number of elements read so far.
+	 *
+	 *  The number is mod (SIZE_MAX + 1), using C's wrapping
+	 *  unsigned integer arithmetic.
+	 */
+	size_t n_read;
+} csnip_ringbuf2;
+
+size_t csnip_ringbuf2_init(csnip_ringbuf2* rb, size_t min_cap);
+csnip_ringbuf2 csnip_ringbuf2_make(size_t min_cap);
+
+size_t csnip_ringbuf2_used_size(const csnip_ringbuf2* rb);
+size_t csnip_ringbuf2_free_size(const csnip_ringbuf2* rb);
+
+size_t csnip_ringbuf2_get_write_idx(const csnip_ringbuf2* rb,
+				size_t* ret_contig_write_max);
+bool csnip_ringbuf2_add_written(csnip_ringbuf2* rb, size_t n_written);
+
+size_t csnip_ringbuf2_get_read_idx(const csnip_ringbuf2* rb,
+				size_t* ret_contig_read_max);
+bool csnip_ringbuf2_add_read(csnip_ringbuf2* rb, size_t n_read);
+
+#endif /* CSNIP_RINGBUF2_H */
+
+#if defined(CSNIP_SHORT_NAMES) && !defined(CSNIP_RINGBUF2_HAVE_SHORT_NAMES)
+#define ringbuf2		csnip_ringbuf2
+#define ringbuf2_init		csnip_ringbuf2_init
+#define ringbuf2_make		csnip_ringbuf2_make
+#define ringbuf2_used_size	csnip_ringbuf2_used_size
+#define ringbuf2_free_size	csnip_ringbuf2_free_size
+#define ringbuf2_get_write_idx	csnip_ringbuf2_get_write_idx
+#define ringbuf2_add_written	csnip_ringbuf2_add_written
+#define ringbuf2_get_read_idx	csnip_ringbuf2_get_read_idx
+#define ringbuf2_add_read	csnip_ringbuf2_add_read
+#define CSNIP_RINGBUF2_HAVE_SHORT_NAMES
+#endif /* CSNIP_SHORT_NAMES && !CSNIP_RINGBUF2_HAVE_SHORT_NAMES */

test/CMakeLists.txt

@@ -16,6 +16,7 @@ set(tests_c
 	meanvar_test0.c
 	mem_test0.c
 	ringbuf_test.c
+	ringbuf2_test.c
 #	rng_mt_test.c
 	runif_getf_test.c
 	runif_geti_test.c

test/ringbuf2_test.c

@@ -0,0 +1,152 @@
+#include <stdlib.h>
+#include <stdio.h>
+#include <string.h>
+
+#define CSNIP_SHORT_NAMES
+#include <csnip/ringbuf2.h>
+#include <csnip/util.h>
+
+#define CHECK(x) \
+	do { \
+		if (!(x)) { \
+			printf(" FAIL\n"); \
+			fprintf(stderr, "check \"%s\" failed\n", #x); \
+			exit(1); \
+		} \
+	} while (0)
+
+static void test_init_k(int k, int expect)
+{
+	ringbuf2 rb;
+	memset(&rb, 'x', sizeof rb);
+
+	CHECK(ringbuf2_init(&rb, k) == expect);
+	CHECK(rb.cap == expect);
+	CHECK(rb.n_written == 0);
+	CHECK(rb.n_read == 0);
+
+	ringbuf2 rb2 = ringbuf2_make(k);
+	CHECK(rb2.cap == expect);
+	CHECK(rb2.n_written == 0);
+	CHECK(rb2.n_read == 0);
+}
+
+void test_init(void)
+{
+	test_init_k(15, 16);
+	test_init_k(16, 16);
+	test_init_k(17, 32);
+}
+
+/* Create example ring buffers
+ *
+ * - straight has the write index after read
+ * - twisted has the write index before read
+ */
+
+size_t rand_i(int i)
+{
+	size_t ii = i;
+	for (int j = 0; j < 8; ++j) {
+		ii *= 1234567u;
+		ii ^= ii >> 12;
+	}
+	return ii;
+}
+
+ringbuf2 get_rb2_straight(int i, size_t* ret_widx, size_t* ret_ridx)
+{
+	/* Capacity */
+	const size_t cap = ((size_t)1) << (rand_i(i) & 31);
+
+	/* Indices */
+	size_t a = rand_i(i + 1) % cap;
+	size_t b = rand_i(i + 2) % cap;
+	const size_t widx = Max(a, b);
+	const size_t ridx = Min(a, b);
+
+	ringbuf2 rb = {
+		.cap = cap,
+		.n_written = widx + i * cap,
+		.n_read = ridx + i * cap,
+	};
+
+	*ret_widx = widx;
+	*ret_ridx = ridx;
+	return rb;
+}
+
+ringbuf2 get_rb2_twisted(int i, size_t* ret_widx, size_t* ret_ridx)
+{
+	size_t widx0, ridx0;
+	ringbuf2 rb_s = get_rb2_straight(i, &widx0, &ridx0);
+	ringbuf2 rb = (ringbuf2) {
+		.cap = rb_s.cap,
+		.n_written = ridx0 + rb_s.cap,
+		.n_read = widx0,
+	};
+
+	*ret_widx = ridx0;
+	*ret_ridx = widx0;
+	return rb;
+}
+
+void straighttwisted_checks(void)
+{
+	for (int i = 0; i < 1024; ++i) {
+		/* Straight checks */
+		printf("Straight checks, i = %d\n", i);
+		size_t widx, ridx;
+		ringbuf2 rb = get_rb2_straight(i, &widx, &ridx);
+		CHECK(ringbuf2_used_size(&rb) == widx - ridx);
+		CHECK(ringbuf2_free_size(&rb)
+			== rb.cap - ringbuf2_used_size(&rb));
+		CHECK(ringbuf2_get_write_idx(&rb, NULL) == widx);
+		CHECK(ringbuf2_get_read_idx(&rb, NULL) == ridx);
+		size_t n_contig;
+		CHECK(ringbuf2_get_write_idx(&rb, &n_contig) == widx);
+		CHECK(n_contig == rb.cap - widx);
+		CHECK(ringbuf2_get_read_idx(&rb, &n_contig) == ridx);
+		CHECK(n_contig == widx - ridx);
+		if (ringbuf2_free_size(&rb) > 0) {
+			CHECK(ringbuf2_add_written(&rb, 1));
+			CHECK(ringbuf2_get_write_idx(&rb, NULL)
+				== (widx + 1) % rb.cap);
+		}
+		if (ringbuf2_used_size(&rb) > 0) {
+			CHECK(ringbuf2_add_read(&rb, 1));
+			CHECK(ringbuf2_get_read_idx(&rb, NULL)
+				== (ridx + 1) % rb.cap);
+		}
+
+		/* Twisted checks */
+		printf("Twisted checks, i = %d\n", i);
+		rb = get_rb2_twisted(i, &widx, &ridx);
+		CHECK(ringbuf2_used_size(&rb) == rb.cap + widx - ridx);
+		CHECK(ringbuf2_free_size(&rb) == ridx - widx);
+		CHECK(ringbuf2_get_write_idx(&rb, NULL) == widx);
+		CHECK(ringbuf2_get_read_idx(&rb, NULL) == ridx);
+		CHECK(ringbuf2_get_write_idx(&rb, &n_contig) == widx);
+		CHECK(n_contig == ridx - widx);
+		CHECK(ringbuf2_get_read_idx(&rb, &n_contig) == ridx);
+		CHECK(n_contig == rb.cap - ridx);
+		if (ringbuf2_free_size(&rb) > 0) {
+			CHECK(ringbuf2_add_written(&rb, 1));
+			CHECK(ringbuf2_get_write_idx(&rb, NULL)
+				== (widx + 1) % rb.cap);
+		}
+		if (ringbuf2_used_size(&rb) > 0) {
+			CHECK(ringbuf2_add_read(&rb, 1));
+			CHECK(ringbuf2_get_read_idx(&rb, NULL)
+				== (ridx + 1) % rb.cap);
+		}
+	}
+}
+
+
+int main(int argc, char** argv)
+{
+	test_init();
+	straighttwisted_checks();
+	return 0;
+}