The Streamer class. This class implements a circular byte-buffer with thread and interrupt safe methods for writing-to and reading-from the buffer. Objects of this class type are designed to be shared between threads, or between threads and interrupts. More...

#include <streamer.h>

Public Member Functions
void	Init (uint8_t *pau8Buffer_, uint16_t u16Size_)
	Init. Initialize the Streamer object prior to its use, providing a blob of memory for the object to manage. More...

bool	Read (uint8_t *pu8Data_)
	Read. Read a byte of data from the stream, if available. More...

uint16_t	Read (uint8_t *pu8Data_, uint16_t u16Len_)
	Read. Read from the stream until a specified number of bytes have been read, or the stream is exhausted. More...

bool	Write (uint8_t u8Data_)
	Write. Write a byte of data into the stream. More...

uint16_t	Write (const uint8_t *pu8Data_, uint16_t u16Len_)
	Write. Write a maximum number of bytes to the stream. More...

bool	Claim (uint8_t **pu8Addr_)
	Claim. Claim a byte of data for writing, without actually writing into it. When the writer is ready to write into the data byte as a result of another operation, it can then populate the byte. More...

void	Lock (uint8_t *pu8LockAddr_)
	Lock. When the lock is set, a client can neither read from, or write to the buffer at the index specified. This is used to in conjunction with Claim to safely reserve data from the buffer, while preventing race conditions occurring as a result of a consumer acting on the data before it is ready. More...

void	Unlock (void)
	Unlock. Reset the lock pointer in the object, allowing a consumer to read any previously unavailable data that might still be in the stream. More...

uint16_t	GetAvailable (void)
	GetAvailable. More...

bool	CanRead (void)
	CanRead. More...

bool	CanWrite (void)
	CanWrite. More...

bool	IsEmpty (void)
	IsEmpty. More...

Private Attributes
uint8_t *	m_pau8Buffer
	Pointer to the buffer managed in this object. More...

uint8_t *	m_pu8LockAddr
	Address of the lock point in the stream. More...

uint16_t	m_u16Size
	Size of the stream's circular buffer (in bytes) More...

uint16_t	m_u16Avail
	Number of bytes free in the stream. More...

uint16_t	m_u16Head
	Current head index (write to) of the stream. More...

uint16_t	m_u16Tail
	Current tail index (read from) of the stream. More...

Detailed Description

The Streamer class. This class implements a circular byte-buffer with thread and interrupt safe methods for writing-to and reading-from the buffer. Objects of this class type are designed to be shared between threads, or between threads and interrupts.

Definition at line 35 of file streamer.h.

Member Function Documentation

◆ CanRead()

bool Mark3::Streamer::CanRead ( void )

CanRead.

Returns: true if the stream has any unread data

Definition at line 200 of file streamer.cpp.

◆ CanWrite()

bool Mark3::Streamer::CanWrite ( void )

CanWrite.

Returns: true if the stream has any free space

Definition at line 211 of file streamer.cpp.

◆ Claim()

bool Mark3::Streamer::Claim ( uint8_t ** pu8Addr_ )

Claim. Claim a byte of data for writing, without actually writing into it. When the writer is ready to write into the data byte as a result of another operation, it can then populate the byte.

This method is useful when encoding data from a raw format into a packet-based format, where one byte of input may result in multiple bytes of output being generated. Especially in cases where a user wants to write to a stream while a peripheral reads from it to transmisit its contents asynchronously (i.e. an interrupt-driven UART consuming a data packet, where the packet is being framed and consumed simultaneously).

This should be used in conjunction with the Lock method and judicious use of critical sections to prevent race conditions.

Parameters

pu8Addr_ [out] Pointer to a byte pointer that will contain the address of the "claimed" byte on success.

Returns: true if successful, false if buffer full or locked.

Definition at line 224 of file streamer.cpp.

◆ GetAvailable()

uint16_t Mark3::Streamer::GetAvailable ( void )

inline

GetAvailable.

Returns: The current number of bytes available for write in the streams

Definition at line 134 of file streamer.h.

◆ Init()

void Mark3::Streamer::Init	(	uint8_t *	pau8Buffer_,
		uint16_t	u16Size_
	)

Init. Initialize the Streamer object prior to its use, providing a blob of memory for the object to manage.

Parameters

pau8Buffer_	Blob of memory to use as a circular buffer
u16Size_	Size of the supplied buffer in bytes

Definition at line 27 of file streamer.cpp.

◆ IsEmpty()

bool Mark3::Streamer::IsEmpty ( void )

IsEmpty.

Returns: true if the stream is empty

Definition at line 264 of file streamer.cpp.

◆ Lock()

void Mark3::Streamer::Lock ( uint8_t * pu8LockAddr_ )

Lock. When the lock is set, a client can neither read from, or write to the buffer at the index specified. This is used to in conjunction with Claim to safely reserve data from the buffer, while preventing race conditions occurring as a result of a consumer acting on the data before it is ready.

Parameters

pu8LockAddr_ Address (within the stream) to set as the lockpoint.

Definition at line 250 of file streamer.cpp.

◆ Read() [1/2]

bool Mark3::Streamer::Read ( uint8_t * pu8Data_ )

Read. Read a byte of data from the stream, if available.

Parameters

pu8Data_ Pointer to read data into from the stream

Returns: true if data was read, false if data unavailable or buffer locked

Definition at line 38 of file streamer.cpp.

◆ Read() [2/2]

uint16_t Mark3::Streamer::Read	(	uint8_t *	pu8Data_,
		uint16_t	u16Len_
	)

Read. Read from the stream until a specified number of bytes have been read, or the stream is exhausted.

Parameters

pu8Data_	pointer to an array of data read into
u16Len_	maximum number of bytes to read

Returns: number of bytes read

Definition at line 64 of file streamer.cpp.

◆ Unlock()

void Mark3::Streamer::Unlock ( void )

Unlock. Reset the lock pointer in the object, allowing a consumer to read any previously unavailable data that might still be in the stream.

Definition at line 257 of file streamer.cpp.

◆ Write() [1/2]

bool Mark3::Streamer::Write ( uint8_t u8Data_ )

Write. Write a byte of data into the stream.

Parameters

u8Data_ Data byte to be written into the stream

Returns: true if byte was written, false on buffer full or buffer locked at index.

Definition at line 120 of file streamer.cpp.

◆ Write() [2/2]

uint16_t Mark3::Streamer::Write	(	const uint8_t *	pu8Data_,
		uint16_t	u16Len_
	)

Write. Write a maximum number of bytes to the stream.

Parameters

pu8Data_	pointer to an array of bytes to write out to the stream
u16Len_	Length of data held in the array

Returns: number of bytes written to the stream

Definition at line 144 of file streamer.cpp.

Member Data Documentation

◆ m_pau8Buffer

uint8_t* Mark3::Streamer::m_pau8Buffer

private

Pointer to the buffer managed in this object.

Definition at line 154 of file streamer.h.

◆ m_pu8LockAddr

uint8_t* Mark3::Streamer::m_pu8LockAddr

private

Address of the lock point in the stream.

Definition at line 155 of file streamer.h.

◆ m_u16Avail

uint16_t Mark3::Streamer::m_u16Avail

private

Number of bytes free in the stream.

Definition at line 158 of file streamer.h.

◆ m_u16Head

uint16_t Mark3::Streamer::m_u16Head

private

Current head index (write to) of the stream.

Definition at line 159 of file streamer.h.

◆ m_u16Size

uint16_t Mark3::Streamer::m_u16Size

private

Size of the stream's circular buffer (in bytes)

Definition at line 157 of file streamer.h.

◆ m_u16Tail

uint16_t Mark3::Streamer::m_u16Tail

private

Current tail index (read from) of the stream.

Definition at line 160 of file streamer.h.

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

/mnt/c/Users/moslevin/m3-repo2/kernel/lib/streamer/public/streamer.h
/mnt/c/Users/moslevin/m3-repo2/kernel/lib/streamer/streamer.cpp

Public Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ CanRead()

◆ CanWrite()

◆ Claim()

◆ GetAvailable()

◆ Init()

◆ IsEmpty()

◆ Lock()

◆ Read() [1/2]

◆ Read() [2/2]

◆ Unlock()

◆ Write() [1/2]

◆ Write() [2/2]

Member Data Documentation

◆ m_pau8Buffer

◆ m_pu8LockAddr

◆ m_u16Avail

◆ m_u16Head

◆ m_u16Size

◆ m_u16Tail