quakeforge/include/QF/ringbuffer.h

/*
	ringbuffer.h

	ring buffer

	Copyright (C) 2020  Bill Currie <bill@taniwha.org>

	This program is free software; you can redistribute it and/or
	modify it under the terms of the GNU General Public License
	as published by the Free Software Foundation; either version 2
	of the License, or (at your option) any later version.

	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

	See the GNU General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with this program; if not, write to:

		Free Software Foundation, Inc.
		59 Temple Place - Suite 330
		Boston, MA  02111-1307, USA

*/

#ifndef __QF_ringbuffer_h
#define __QF_ringbuffer_h

/** Type declaration for a type-safe ring buffer.
 *
 * While not in itself thread-safe, the buffer is designed (and tested) to be
 * used in a threaded environment using suitable locking mechanisms.
 *
 * \param type		The type of data element stored in the ring buffer.
 * \param size		The number of objects in the ring buffer. Note that the
 * 					actual capacity of the buffer is `size - 1` due to the
 * 					way ring buffers work.
 *
 * \note On its own, this is not thread-safe. Suitable locking is required.
 */
#define RING_BUFFER(type, size) 	\
	struct {						\
		type        buffer[size];	\
		unsigned    head;			\
		unsigned    tail;			\
	}

/** Type declaration for a type-safe ring buffer with atomic head and tail.
 *
 * \param type		The type of data element stored in the ring buffer.
 * \param size		The number of objects in the ring buffer. Note that the
 * 					actual capacity of the buffer is `size - 1` due to the
 * 					way ring buffers work.
 *
 * \note This is suitable only for single-reader/single-writer unless
 * additional locking is provided for multi-user side. This means `head` must
 * have an associated lock for multiple writers, and `tail` must have an
 * associated lock for multiple readers. For multi-reader + multi-writer, it
 * may be better to use RING_BUFFER with suitable locking.
 */
#define RING_BUFFER_ATOMIC(type, size) 	\
	struct {							\
		type        buffer[size];		\
		_Atomic unsigned head;			\
		_Atomic unsigned tail;			\
	}

#define RB_buffer_size(ring_buffer)							\
	({	__auto_type rb_s = (ring_buffer);					\
		sizeof (rb_s->buffer) / sizeof (rb_s->buffer[0]);	\
	})

/** Return the amount of space available for writing in the ring buffer.
 *
 * Use this to know how much data can be written (RB_WRITE_DATA()) or acquired
 * (RB_ACQUIRE()), or just to see if any space is available.
 *
 * \note Does NOT affect buffer state.
 *
 * \param ring_buffer	The ring buffer to check for available space.
 */
#define RB_SPACE_AVAILABLE(ring_buffer)										\
	({	__auto_type rb = &(ring_buffer);									\
		(rb->tail + RB_buffer_size(rb) - rb->head - 1) % RB_buffer_size(rb);\
	})

/** Return the number of objects available in the ring buffer.
 *
 * Use this to know how much data can be read (RB_READ_DATA()) or discarded
 * (RB_RELEASE()), or just to see if any data is available.
 *
 * \note Does NOT affect buffer state.
 *
 * \param ring_buffer	The ring buffer to check for available data.
 */
#define RB_DATA_AVAILABLE(ring_buffer)										\
	({	__auto_type rb = &(ring_buffer);									\
		(rb->head + RB_buffer_size (rb) - rb->tail) % RB_buffer_size (rb);	\
	})

/** Write \a count objects from \a data to the buffer, wrapping if necessary.
 *
 * \note Affects buffer state (advances the head).
 *
 * \note Does NOT check that the space is available. It is the caller's
 * responsitiblity to do so using RB_SPACE_AVAILABLE().
 *
 * \param ring_buffer	The ring buffer to which the data will be written.
 * \param data			Pointer to the data to be copied into the ring buffer.
 * \param count			unsigned int. The number of objects to copy from
 *						\a data
 */
#define RB_WRITE_DATA(ring_buffer, data, count)								\
	({	__auto_type rb = &(ring_buffer);									\
		const typeof (rb->buffer[0]) *d = (data);							\
		unsigned    c = (count);											\
		unsigned    h = rb->head;											\
		unsigned    new_head = (h + c) % RB_buffer_size (rb);				\
		if (c > RB_buffer_size (rb) - h) {									\
			memcpy (rb->buffer + h, d,										\
					(RB_buffer_size (rb) - h) * sizeof (rb->buffer[0]));	\
			c -= RB_buffer_size (rb) - h;									\
			d += RB_buffer_size (rb) - h;									\
			h = 0;															\
		}																	\
		memcpy (rb->buffer + h, d, c * sizeof (rb->buffer[0]));				\
		rb->head = new_head;												\
	})

/** Acquire \a count objects from the buffer, wrapping if necessary.
 *
 * \note Affects buffer state (advances the head).
 *
 * \note Does NOT check that the space is available. It is the caller's
 * responsitiblity to do so using RB_SPACE_AVAILABLE().
 *
 * \param ring_buffer	The ring buffer to which the data will be written.
 * \param count			unsigned int. The number of objects to copy from
 *						\a data.
 * \return				Address of the first object acquired.
 */
#define RB_ACQUIRE(ring_buffer, count)										\
	({	__auto_type rb = &(ring_buffer);									\
		unsigned    c = (count);											\
		unsigned    h = rb->head;											\
		unsigned    new_head = (h + c) % RB_buffer_size (rb);				\
		__auto_type head_addr = &rb->buffer[h];								\
		rb->head = new_head;												\
		head_addr;															\
	})

/** Read \a count objects from the buffer to \a data, wrapping if necessary.
 *
 * \note Affects buffer state (advances the tail).
 *
 * \note Does NOT check that the data is available. It is the caller's
 * responsitiblity to do so using RB_DATA_AVAILABLE().
 *
 * \param ring_buffer	The ring buffer from which the data will be read.
 * \param data			Pointer to the location into which data will be copied
 * 						from the ring buffer.
 * \param count			unsigned int. The number of objects to copy from
 *						the buffer into \a data
 */
#define RB_READ_DATA(ring_buffer, data, count)								\
	({	__auto_type rb = &(ring_buffer);									\
		typeof (&rb->buffer[0]) d = (data);									\
		unsigned    c = (count);											\
		unsigned    oc = c;													\
		unsigned    t = rb->tail;											\
		unsigned    new_tail = (t + oc) % RB_buffer_size (rb);				\
		if (c > RB_buffer_size (rb) - t) {									\
			memcpy (d, rb->buffer + t,										\
					(RB_buffer_size (rb) - t) * sizeof (rb->buffer[0]));	\
			c -= RB_buffer_size (rb) - t;									\
			d += RB_buffer_size (rb) - t;									\
			t = 0;															\
		}																	\
		memcpy (d, rb->buffer + t, c * sizeof (rb->buffer[0]));				\
		rb->tail = new_tail;												\
	})

/** Discard \a count objects from the ring buffer.
 *
 * \note Affects buffer state (advances the tail).
 *
 * \note Does NOT check that the data is available. It is the caller's
 * responsitiblity to do so using RB_DATA_AVAILABLE().
 *
 * \param ring_buffer	The ring buffer from which the objects will be
 * 						discarded.
 * \param count			The number of objects to discard.
 */
#define RB_RELEASE(ring_buffer, count)										\
	({	__auto_type rb = &(ring_buffer);									\
		unsigned    c = (count);											\
		unsigned    t = rb->tail;											\
		rb->tail = (t + c) % RB_buffer_size (rb);							\
	})

/** Access a single item from the buffer without affecting buffer state.
 *
 * \note Does NOT affect buffer state.
 *
 * \note Does NOT check that the data is available. It is the caller's
 * responsitiblity to do so using RB_DATA_AVAILABLE().
 *
 * \param ring_buffer	The ring buffer from which to access the object.
 * \param ahead			The tail-relative index of the object to access from
 *						the buffer. Valid range is 0 to
 *						`RB_DATA_AVAILABLE() - 1`
 * \return				Address of the accessed element
 */
#define RB_PEEK_DATA(ring_buffer, ahead)						\
	({	__auto_type rb = &(ring_buffer);						\
		&rb->buffer[(rb->tail + ahead) % RB_buffer_size (rb)];	\
	})

/** WRite a single item to the buffer without affecting buffer state.
 *
 * \note Does NOT affect buffer state.
 *
 * \note Does NOT check that the data is available. It is the caller's
 * responsitiblity to do so using RB_DATA_AVAILABLE().
 *
 * \param ring_buffer	The ring buffer from which to read the object.
 * \param ahead			The tail-relative index of the buffer object to write.
 *						Valid range is 0 to `RB_DATA_AVAILABLE() - 1`
 * \param data			The data to write to the buffer.
 */
#define RB_POKE_DATA(ring_buffer, ahead, data)							\
	({	__auto_type rb = &(ring_buffer);								\
		rb->buffer[(rb->tail + ahead) % RB_buffer_size (rb)] = (data);	\
	})

#endif//__QF_ringbuffer_h