Thread-safe, lock-free circular buffer for one-producer and one-consumer. More...

#include "distortos/devices/communication/SerialPort.hpp"

Public Member Functions
constexpr	CircularBuffer (void *const buffer, const size_t size)
	CircularBuffer's constructor. More...

constexpr	CircularBuffer (const void *const buffer, const size_t size)
	CircularBuffer's constructor, read-only variant. More...

void	clear ()
	Clears circular buffer. More...

size_t	getCapacity () const

std::pair< const uint8_t *, size_t >	getReadBlock () const

size_t	getSize () const

std::pair< uint8_t *, size_t >	getWriteBlock () const

void	increaseReadPosition (const size_t value)
	Increases read position by given value. More...

void	increaseWritePosition (const size_t value)
	Increases write position by given value. More...

bool	isEmpty () const

bool	isFull () const

bool	isReadOnly () const

Private Member Functions
std::pair< uint8_t *, size_t >	getBlock (const size_t begin, const size_t end) const
	Gets first contiguous block between position1 and position2. More...

size_t	increasePosition (const size_t position, const size_t value)
	Increases given position by given value. More...

Static Private Member Functions
static constexpr bool	isEmpty (const size_t readPosition, const size_t writePosition)
	Tests for empty circular buffer. More...

static constexpr bool	isFull (const size_t readPosition, const size_t writePosition)
	Tests for full circular buffer. More...

Private Attributes
uint8_t *	buffer_
	pointer to beginning of buffer More...

size_t	size_
	size of buffer_, bytes More...

volatile size_t	readPosition_
	current read position More...

volatile size_t	writePosition_
	current write position More...

Static Private Attributes
static constexpr size_t	positionMask_ {SIZE_MAX >> 1}
	bitmask used to extract position from readPosition_ or writePosition_ More...

static constexpr size_t	msbMask_ {~positionMask_}
	bitmask used to extract MSB from readPosition_ or writePosition_ More...

static constexpr size_t	sizeMask_ {SIZE_MAX >> 1}
	bitmask used to extract size from size_ More...

static constexpr size_t	readOnlyMask_ {~sizeMask_}
	bitmask used to extract "read-only" flag from size_ More...

Detailed Description

Thread-safe, lock-free circular buffer for one-producer and one-consumer.

Distinction between empty and full buffer is possible because most significant bits of read and write positions are used as single-bit counters or wrap-arounds. This limits the size of buffer to SIZE_MAX / 2, but allows full utilization of storage (no free slot is needed).

Constructor & Destructor Documentation

◆ CircularBuffer() [1/2]

constexpr distortos::devices::SerialPort::CircularBuffer::CircularBuffer	(	void *const	buffer,
		const size_t	size
	)

inline

CircularBuffer's constructor.

Parameters

[in]	buffer	is a buffer for data
[in]	size	is the size of buffer, bytes, must be less than or equal to SIZE_MAX / 2

◆ CircularBuffer() [2/2]

constexpr distortos::devices::SerialPort::CircularBuffer::CircularBuffer	(	const void *const	buffer,
		const size_t	size
	)

inline

CircularBuffer's constructor, read-only variant.

Parameters

[in]	buffer	is a read-only buffer with data
[in]	size	is the size of buffer, bytes, must be less than or equal to SIZE_MAX / 2

Member Function Documentation

◆ clear()

void distortos::devices::SerialPort::CircularBuffer::clear ( )

inline

Clears circular buffer.

Here is the caller graph for this function:

◆ getBlock()

std::pair<uint8_t*, size_t> distortos::devices::SerialPort::CircularBuffer::getBlock	(	const size_t	begin,
		const size_t	end
	)		const

inlineprivate

Gets first contiguous block between position1 and position2.

This function does not treat empty or full buffer in any special way.

Parameters

[in]	begin	is the beginning position
[in]	end	is the ending position

Returns: first contiguous block (as a pair with pointer and size) starting at begin and not crossing end or end of buffer

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getCapacity()

size_t distortos::devices::SerialPort::CircularBuffer::getCapacity ( ) const

inline

Returns: total capacity of circular buffer, bytes

Here is the caller graph for this function:

◆ getReadBlock()

std::pair< const uint8_t *, size_t > distortos::devices::SerialPort::CircularBuffer::getReadBlock ( ) const

Returns: first contiguous block (as a pair with pointer and size) available for reading

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getSize()

size_t distortos::devices::SerialPort::CircularBuffer::getSize ( ) const

inline

Returns: total amount of valid data in circular buffer, bytes

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getWriteBlock()

std::pair< uint8_t *, size_t > distortos::devices::SerialPort::CircularBuffer::getWriteBlock ( ) const

Returns: first contiguous block (as a pair with pointer and size) available for writing

Here is the caller graph for this function:

◆ increasePosition()

size_t distortos::devices::SerialPort::CircularBuffer::increasePosition	(	const size_t	position,
		const size_t	value
	)

inlineprivate

Increases given position by given value.

Parameters

[in]	position	is the position that will be incremented
[in]	value	is the value which will be added to position, must come from previous call to getReadBlock() / getWriteBlock()

Returns: position incremented by value

Here is the call graph for this function:

Here is the caller graph for this function:

◆ increaseReadPosition()

void distortos::devices::SerialPort::CircularBuffer::increaseReadPosition ( const size_t value )

inline

Increases read position by given value.

Parameters

[in] value is the value which will be added to read position, must come from previous call to getReadBlock()

Here is the call graph for this function:

Here is the caller graph for this function:

◆ increaseWritePosition()

void distortos::devices::SerialPort::CircularBuffer::increaseWritePosition ( const size_t value )

inline

Increases write position by given value.

Parameters

[in] value is the value which will be added to write position, must come from previous call to getWriteBlock()

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isEmpty() [1/2]

bool distortos::devices::SerialPort::CircularBuffer::isEmpty ( ) const

inline

Returns: true if circular buffer is empty, false otherwise

Here is the caller graph for this function:

◆ isEmpty() [2/2]

static constexpr bool distortos::devices::SerialPort::CircularBuffer::isEmpty	(	const size_t	readPosition,
		const size_t	writePosition
	)

inlinestaticprivate

Tests for empty circular buffer.

The buffer is empty if read and write positions are equal, including their MSBs.

Parameters

[in]	readPosition	is the value of readPosition_
[in]	writePosition	is the value of writePosition_

Returns: true if circular buffer is empty, false otherwise

◆ isFull() [1/2]

bool distortos::devices::SerialPort::CircularBuffer::isFull ( ) const

inline

Returns: true if circular buffer is full, false otherwise

Here is the caller graph for this function:

◆ isFull() [2/2]

static constexpr bool distortos::devices::SerialPort::CircularBuffer::isFull	(	const size_t	readPosition,
		const size_t	writePosition
	)

inlinestaticprivate

Tests for full circular buffer.

The buffer is full if masked read and write positions are equal, but their MSBs are different.

Parameters

[in]	readPosition	is the value of readPosition_
[in]	writePosition	is the value of writePosition_

Returns: true if circular buffer is full, false otherwise

◆ isReadOnly()

bool distortos::devices::SerialPort::CircularBuffer::isReadOnly ( ) const

inline

Returns: true if circular buffer is read-only, false otherwise

Member Data Documentation

◆ buffer_

uint8_t* distortos::devices::SerialPort::CircularBuffer::buffer_

private

pointer to beginning of buffer

◆ msbMask_

constexpr size_t distortos::devices::SerialPort::CircularBuffer::msbMask_ {~positionMask_}

staticprivate

bitmask used to extract MSB from readPosition_ or writePosition_

◆ positionMask_

constexpr size_t distortos::devices::SerialPort::CircularBuffer::positionMask_ {SIZE_MAX >> 1}

staticprivate

bitmask used to extract position from readPosition_ or writePosition_

◆ readOnlyMask_

constexpr size_t distortos::devices::SerialPort::CircularBuffer::readOnlyMask_ {~sizeMask_}

staticprivate

bitmask used to extract "read-only" flag from size_

◆ readPosition_

volatile size_t distortos::devices::SerialPort::CircularBuffer::readPosition_

private

current read position

◆ size_

size_t distortos::devices::SerialPort::CircularBuffer::size_

private

size of buffer_, bytes

◆ sizeMask_

constexpr size_t distortos::devices::SerialPort::CircularBuffer::sizeMask_ {SIZE_MAX >> 1}

staticprivate

bitmask used to extract size from size_

◆ writePosition_

volatile size_t distortos::devices::SerialPort::CircularBuffer::writePosition_

private

current write position

The documentation for this class was generated from the following files:

include/distortos/devices/communication/SerialPort.hpp
source/devices/communication/SerialPort.cpp

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ CircularBuffer() [1/2]

◆ CircularBuffer() [2/2]

Member Function Documentation

◆ clear()

◆ getBlock()

◆ getCapacity()

◆ getReadBlock()

◆ getSize()

◆ getWriteBlock()

◆ increasePosition()

◆ increaseReadPosition()

◆ increaseWritePosition()

◆ isEmpty() [1/2]

◆ isEmpty() [2/2]

◆ isFull() [1/2]

◆ isFull() [2/2]

◆ isReadOnly()

Member Data Documentation

◆ buffer_

◆ msbMask_

◆ positionMask_

◆ readOnlyMask_

◆ readPosition_

◆ size_

◆ sizeMask_

◆ writePosition_