distortos  v0.7.0
object-oriented C++ RTOS for microcontrollers
distortos::devices::SerialPort::CircularBuffer Class Reference

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]bufferis a buffer for data
[in]sizeis 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]bufferis a read-only buffer with data
[in]sizeis 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]beginis the beginning position
[in]endis 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]positionis the position that will be incremented
[in]valueis 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]valueis 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]valueis 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]readPositionis the value of readPosition_
[in]writePositionis 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]readPositionis the value of readPosition_
[in]writePositionis 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: