Ringbuffer class missing from API documentation?

[james-smith-za]

spead2/include/spead2/common_ringbuffer.h

Lines 262 to 285 in 1512437

	/**
	* Ring buffer with blocking and non-blocking push and pop. It supports
	* non-copyable objects using move semantics. The producer may signal that it
	* has finished producing data by calling @ref stop, which will gracefully shut
	* down consumers as well as other producers. This class is fully thread-safe
	* for multiple producers and consumers.
	*
	* \internal
	*
	* The design is mostly standard: head and tail pointers, and semaphores
	* indicating the number of free and filled slots. One slot is always left
	* empty so that the destructor can distinguish between empty and full without
	* consulting the semaphores.
	*
	* The interesting part is @ref stop. On the producer side, this sets @ref
	* stopped, which is protected by the tail mutex to immediately prevent any
	* other pushes. On the consumer side, it sets @ref stop_position (protected
	* by the head mutex), so that consumers only get @ref ringbuffer_stopped
	* after consuming already-present elements. To wake everything up and prevent
	* any further waits, @ref stop ups both semaphores, and any functions that
	* observe a stop condition after downing a semaphore will re-up it. This
	* causes the semaphore to be transiently unavailable, which leads to the need
	* for @ref throw_empty_or_stopped and @ref throw_full_or_stopped.
	*/

I wasn't able to find this class documented anywhere on readthedocs. Was that by design?

[bmerry]

Probably just because I haven't put a lot of effort into the C++ docs. It's not needed by everybody because it's normally hidden behind spead2::recv::ring_stream.

[james-smith-za]

Good point. I came looking for it because of how it gets used in kafgpu, and I couldn't find anything in readthedocs. The documentation in the code was what I needed, but I just thought it was weird that Sphinx didn't include it.

[bmerry]

We can leave this bug open - one day I should get around to improving the C++ docs on readthedocs.