Base class that provides the standard stream buffer interface to FreeRTOS::StreamBuffer and FreeRTOS::StaticStreamBuffer. More...

#include <FreeRTOS/StreamBuffer.hpp>

Inheritance diagram for FreeRTOS::StreamBufferBase:

[legend]

Public Member Functions
	StreamBufferBase (const StreamBufferBase &)=delete

StreamBufferBase &	operator= (const StreamBufferBase &)=delete

bool	isValid () const
	Function that checks if the underlying stream buffer handle is not NULL. This should be used to ensure a stream buffer has been created correctly.

size_t	send (const void *data, const size_t length, const TickType_t ticksToWait=portMAX_DELAY) const
	Function that calls `size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer, const void *pvTxData, size_t xDataLengthBytes, TickType_t xTicksToWait )`

size_t	sendFromISR (bool &higherPriorityTaskWoken, const void *data, const size_t length) const
	Function that calls `size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer, const void pvTxData, size_t xDataLengthBytes, BaseType_t pxHigherPriorityTaskWoken )`

size_t	sendFromISR (const void *data, const size_t length) const
	Function that calls `size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer, const void pvTxData, size_t xDataLengthBytes, BaseType_t pxHigherPriorityTaskWoken )`

size_t	receive (void *buffer, const size_t bufferLength, const TickType_t ticksToWait=portMAX_DELAY) const
	Function that calls `size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer, void *pvRxData, size_t xBufferLengthBytes, TickType_t xTicksToWait )`

size_t	receiveFromISR (bool &higherPriorityTaskWoken, void *buffer, const size_t bufferLength) const
	Function that calls `size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer, void pvRxData, size_t xBufferLengthBytes, BaseType_t pxHigherPriorityTaskWoken )`

size_t	receiveFromISR (void *buffer, const size_t bufferLength) const
	Function that calls `size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer, void pvRxData, size_t xBufferLengthBytes, BaseType_t pxHigherPriorityTaskWoken )`

size_t	bytesAvailable () const
	Function that calls `size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer )`

size_t	spacesAvailable () const
	Function that calls `size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer )`

bool	setTriggerLevel (const size_t triggerLevel=0) const
	Function that calls `BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel )`

bool	reset () const
	Function that calls `BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer )`

bool	isEmpty () const
	Function that calls `BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer )`

bool	isFull () const
	Function that calls `BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer )`

Static Public Member Functions
static void *	operator new (size_t)=delete

static void *	operator new[] (size_t)=delete

static void *	operator new (size_t, void *ptr)

static void *	operator new[] (size_t, void *ptr)

Private Member Functions
	~StreamBufferBase ()
	Destroy the StreamBufferBase object by calling `void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer )`

	StreamBufferBase (StreamBufferBase &&) noexcept=default

StreamBufferBase &	operator= (StreamBufferBase &&) noexcept=default

Private Attributes
StreamBufferHandle_t	handle = NULL

Friends
class	StreamBuffer

template<size_t >
class	StaticStreamBuffer

Detailed Description

Base class that provides the standard stream buffer interface to FreeRTOS::StreamBuffer and FreeRTOS::StaticStreamBuffer.

Note: This class is not intended to be instantiated by the user. Use FreeRTOS::StreamBuffer or FreeRTOS::StaticStreamBuffer.

Warning: Uniquely among FreeRTOS objects, the stream buffer implementation (so also the message buffer implementation, as message buffers are built on top of stream buffers) assumes there is only one task or interrupt that will write to the buffer (the writer), and only one task or interrupt that will read from the buffer (the reader). It is safe for the writer and reader to be different tasks or interrupts, but, unlike other FreeRTOS objects, it is not safe to have multiple different writers or multiple different readers. If there are to be multiple different writers then the application writer must place each call to a writing API function (such as send()) inside a critical section and set the send block time to 0. Likewise, if there are to be multiple different readers then the application writer must place each call to a reading API function (such as read()) inside a critical section and set the receive block time to 0.

Constructor & Destructor Documentation

◆ ~StreamBufferBase()

FreeRTOS::StreamBufferBase::~StreamBufferBase ( )

inlineprivate

Destroy the StreamBufferBase object by calling void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer )

StreamBuffer.hpp

See also: https://www.freertos.org/vStreamBufferDelete.html

Deletes a stream buffer and free the allocated memory.

Member Function Documentation

◆ bytesAvailable()

size_t FreeRTOS::StreamBufferBase::bytesAvailable ( ) const

inline

Function that calls size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer )

StreamBuffer.hpp

See also: https://www.freertos.org/xStreamBufferBytesAvailable.html

Queries the stream buffer to see how much data it contains, which is equal to the number of bytes that can be read from the stream buffer before the stream buffer would be empty.

Returns: size_t The number of bytes that can be read from the stream buffer before the stream buffer would be empty.

◆ isEmpty()

bool FreeRTOS::StreamBufferBase::isEmpty ( ) const

inline

Function that calls BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer )

StreamBuffer.hpp

See also: https://www.freertos.org/xStreamBufferIsEmpty.html

Queries a stream buffer to see if it is empty. A stream buffer is empty if it does not contain any data.

Returns: true If the stream buffer is empty.; false Otherwise.

◆ isFull()

bool FreeRTOS::StreamBufferBase::isFull ( ) const

inline

Function that calls BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer )

StreamBuffer.hpp

See also: https://www.freertos.org/xStreamBufferIsFull.html

Queries a stream buffer to see if it is full. A stream buffer is full if it does not have any free space, and therefore cannot accept any more data.

Returns: true If the stream buffer is full.; false Otherwise.

◆ isValid()

bool FreeRTOS::StreamBufferBase::isValid ( ) const

inline

Function that checks if the underlying stream buffer handle is not NULL. This should be used to ensure a stream buffer has been created correctly.

StreamBuffer.hpp

Return values

true	If the handle is not NULL.
false	If the handle is NULL.

◆ receive()

size_t FreeRTOS::StreamBufferBase::receive	(	void *	buffer,
		const size_t	bufferLength,
		const TickType_t	ticksToWait = `portMAX_DELAY`
	)		const

inline

Function that calls size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer, void *pvRxData, size_t xBufferLengthBytes, TickType_t xTicksToWait )

StreamBuffer.hpp

See also: https://www.freertos.org/xStreamBufferReceive.html

Receives bytes from a stream buffer.

Use receive() to read from a stream buffer from a task. Use receiveFromISR() to read from a stream buffer from an interrupt service routine (ISR).

Parameters

buffer	A pointer to the buffer into which the received bytes will be copied.
bufferLength	The length of the buffer pointed to by the data parameter. This sets the maximum number of bytes to receive in one call. receive() will return as many bytes as possible up to a maximum set by length.
ticksToWait	The maximum amount of time the task should remain in the Blocked state to wait for data to become available if the stream buffer is empty. receive() will return immediately if ticksToWait is zero. The block time is specified in tick periods, so the absolute time it represents is dependent on the tick frequency. The macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds into a time specified in ticks. Setting ticksToWait to portMAX_DELAY will cause the task to wait indefinitely (without timing out), provided INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. A task does not use any CPU time when it is in the Blocked state.

Returns: size_t The number of bytes read from the stream buffer. This will be the number of bytes available up to a maximum of length.

Example Usage

#include <FreeRTOS/StreamBuffer.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  MyTask() : streamBuffer(100) {}
  void taskFunction() final;
  FreeRTOS::StreamBuffer streamBuffer;
};
 
void MyTask::taskFunction() {
  uint8_t ucRxData[20];
  size_t xReceivedBytes;
 
  // Receive up to another sizeof( ucRxData ) bytes from the stream buffer. Wait
  // in the Blocked state (so not using any CPU processing time) for a maximum
  // of 100ms for the full sizeof( ucRxData ) number of bytes to be available.
  xReceivedBytes = streamBuffer.receive((void*)ucRxData, sizeof(ucRxData),
                                        pdMS_TO_TICKS(20));
 
  if (xReceivedBytes > 0) {
    // A ucRxData contains another xRecievedBytes bytes of data, which can be
    // processed here...
  }
 
  // Rest of task code.
}

◆ receiveFromISR() [1/2]

size_t FreeRTOS::StreamBufferBase::receiveFromISR	(	bool &	higherPriorityTaskWoken,
		void *	buffer,
		const size_t	bufferLength
	)		const

inline

Function that calls size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer, void *pvRxData, size_t xBufferLengthBytes, BaseType_t *pxHigherPriorityTaskWoken )

StreamBuffer.hpp

See also: https://www.freertos.org/xStreamBufferReceiveFromISR.html

An interrupt safe version of the API function that receives bytes from a stream buffer.

Use receive() to read from a stream buffer from a task. Use receiveFromISR() to read from a stream buffer from an interrupt service routine (ISR).

Parameters

higherPriorityTaskWoken	It is possible that a stream buffer will have a task blocked on it waiting for space to become available. Calling receiveFromISR() can make space available, and so cause a task that is waiting for space to leave the Blocked state. If calling receiveFromISR() causes a task to leave the Blocked state, and the unblocked task has a priority higher than the currently executing task (the task that was interrupted), then, internally, receiveFromISR() will set higherPriorityTaskWoken to true. If receiveFromISR() sets this value to true, then normally a context switch should be performed before the interrupt is exited. That will ensure the interrupt returns directly to the highest priority Ready state task. higherPriorityTaskWoken should be set to false before it is passed into the function. See the code example below for an example.
buffer	A pointer to the buffer into which the received bytes will be copied.
bufferLength	The length of the buffer pointed to by the buffer parameter. This sets the maximum number of bytes to receive in one call. receive() will return as many bytes as possible up to a maximum set by length.

Returns: size_t The number of bytes read from the stream buffer, if any.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/StreamBuffer.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::StaticTask<configMINIMAL_STACK_SIZE> {
 public:
  MyTask() : streamBuffer(100) {}
  void taskFunction() final;
  FreeRTOS::StreamBuffer streamBuffer;
};
 
MyTask task;
 
void anInterruptServiceRoutine() {
  uint8_t ucRxData[20];
  size_t xReceivedBytes;
  bool higherPriorityTaskWoken = false;
 
  // Receive the next stream from the stream buffer.
  xReceivedBytes = task.streamBuffer.receiveFromISR(
      higherPriorityTaskWoken, (void*)ucRxData, sizeof(ucRxData));
 
  if (xReceivedBytes > 0) {
    // ucRxData contains xReceivedBytes read from the stream buffer.  Process
    // the stream here...
  }
 
  // If higherPriorityTaskWoken was set to true inside receiveFromISR() then a
  // task that has a priority above the priority of the currently executing task
  // was unblocked and a context switch should be performed to ensure the ISR
  // returns to the unblocked task.  In most FreeRTOS ports this is done by
  // simply passing higherPriorityTaskWoken into FreeRTOS::yield(), which will
  // test the variables value, and perform the context switch if necessary.
  // Check the documentation for the port in use for port specific instructions.
  FreeRTOS::Kernel::yield();
}

◆ receiveFromISR() [2/2]

size_t FreeRTOS::StreamBufferBase::receiveFromISR	(	void *	buffer,
		const size_t	bufferLength
	)		const

inline

Function that calls size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer, void *pvRxData, size_t xBufferLengthBytes, BaseType_t *pxHigherPriorityTaskWoken )

StreamBuffer.hpp

See also: https://www.freertos.org/xStreamBufferReceiveFromISR.html

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ reset()

bool FreeRTOS::StreamBufferBase::reset ( ) const

inline

Function that calls BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer )

StreamBuffer.hpp

See also: https://www.freertos.org/xStreamBufferReset.html

Resets a stream buffer to its initial, empty, state. Any data that was in the stream buffer is discarded. A stream buffer can only be reset if there are no tasks blocked waiting to either send to or receive from the stream buffer.

Returns: true If the stream buffer is reset.; false If there was a task blocked waiting to send to or read from the stream buffer then the stream buffer was not reset.

◆ send()

size_t FreeRTOS::StreamBufferBase::send	(	const void *	data,
		const size_t	length,
		const TickType_t	ticksToWait = `portMAX_DELAY`
	)		const

inline

Function that calls size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer, const void *pvTxData, size_t xDataLengthBytes, TickType_t xTicksToWait )

StreamBuffer.hpp

See also: https://www.freertos.org/xStreamBufferSend.html

Sends bytes to a stream buffer. The bytes are copied into the stream buffer.

Use send() to write to a stream buffer from a task. Use sendFromISR() to write to a stream buffer from an interrupt service routine (ISR).

Parameters

data	A pointer to the buffer that holds the bytes to be copied into the stream buffer.
length	The maximum number of bytes to copy from data into the stream buffer.
ticksToWait	The maximum amount of time the task should remain in the Blocked state to wait for enough space to become available in the stream buffer, should the stream buffer contain too little space to hold the another length bytes. The block time is specified in tick periods, so the absolute time it represents is dependent on the tick frequency. The macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds into a time specified in ticks. Setting ticksToWait to portMAX_DELAY will cause the task to wait indefinitely (without timing out), provided INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. If a task times out before it can write all length into the buffer it will still write as many bytes as possible. A task does not use any CPU time when it is in the blocked state.

Returns: size_t The number of bytes written to the stream buffer. If a task times out before it can write all length into the buffer it will still write as many bytes as possible.

Example Usage

#include <FreeRTOS/StreamBuffer.hpp>
#include <FreeRTOS/Task.hpp>
#include <cstring>
 
class MyTask : public FreeRTOS::Task {
 public:
  MyTask() : streamBuffer(100) {}
  void taskFunction() final;
  FreeRTOS::StreamBuffer streamBuffer;
};
 
void MyTask::taskFunction() {
  size_t xBytesSent;
  uint8_t ucArrayToSend[] = {0, 1, 2, 3};
  char const *pcStringToSend = "String to send";
 
  // Send an array to the stream buffer, blocking for a maximum of 100ms to wait
  // for enough space to be available in the stream buffer.
  xBytesSent = streamBuffer.send(ucArrayToSend, sizeof(ucArrayToSend),
                                 pdMS_TO_TICKS(100));
 
  if (xBytesSent != sizeof(ucArrayToSend)) {
    // The call to send() times out before there was enough space in the buffer
    // for the data to be written, but it did successfully write xBytesSent
    // bytes.
  }
 
  // Send the string to the stream buffer.  Return immediately if there is not
  // enough space in the buffer.
  xBytesSent = streamBuffer.send(pcStringToSend, strlen(pcStringToSend), 0);
 
  if (xBytesSent != strlen(pcStringToSend)) {
    // The entire string could not be added to the stream buffer because there
    // was not enough free space in the buffer, but xBytesSent bytes were sent.
    // Could try again to send the remaining bytes.
  }
 
  // Rest of task code.
}

◆ sendFromISR() [1/2]

size_t FreeRTOS::StreamBufferBase::sendFromISR	(	bool &	higherPriorityTaskWoken,
		const void *	data,
		const size_t	length
	)		const

inline

Function that calls size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer, const void *pvTxData, size_t xDataLengthBytes, BaseType_t *pxHigherPriorityTaskWoken )

StreamBuffer.hpp

See also: https://www.freertos.org/xStreamBufferSendFromISR.html

Interrupt safe version of the API function that sends a stream of bytes to the stream buffer.

Use send() to write to a stream buffer from a task. Use sendFromISR() to write to a stream buffer from an interrupt service routine (ISR).

Parameters

higherPriorityTaskWoken	It is possible that a stream buffer will have a task blocked on it waiting for data. Calling sendFromISR() can make data available, and so cause a task that was waiting for data to leave the Blocked state. If calling sendFromISR() causes a task to leave the Blocked state, and the unblocked task has a priority higher than the currently executing task (the task that was interrupted), then, internally, sendFromISR() will set higherPriorityTaskWoken to true. If sendFromISR() sets this value to true, then normally a context switch should be performed before the interrupt is exited. This will ensure that the interrupt returns directly to the highest priority Ready state task. higherPriorityTaskWoken should be set to false before it is passed into the function. See the example code below for an example.
data	A pointer to the buffer that holds the bytes to be copied into the stream buffer.
length	The maximum number of bytes to copy from data into the stream buffer.

Returns: size_t The number of bytes written to the stream buffer. If a task times out before it can write all length into the buffer it will still write as many bytes as possible.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/StreamBuffer.hpp>
#include <FreeRTOS/Task.hpp>
#include <cstring>
 
class MyTask : public FreeRTOS::StaticTask<configMINIMAL_STACK_SIZE> {
 public:
  MyTask() : streamBuffer(100) {}
  void taskFunction() final;
  FreeRTOS::StreamBuffer streamBuffer;
};
 
MyTask task;
 
void anInterruptServiceRoutine() {
  char const *pcStringToSend = "String to send";
  bool higherPriorityTaskWoken = false;
 
  // Attempt to send the string to the stream buffer.
  size_t xBytesSent = task.streamBuffer.sendFromISR(
      higherPriorityTaskWoken, pcStringToSend, sizeof(pcStringToSend));
 
  if (xBytesSent != sizeof(pcStringToSend)) {
    // There was not enough free space in the stream buffer for the entire
    // string to be written, ut xBytesSent bytes were written.
  }
 
  // If higherPriorityTaskWoken was set to true inside sendFromISR() then a task
  // that has a priority above the priority of the currently executing task was
  // unblocked and a context switch should be performed to ensure the ISR
  // returns to the unblocked task.  In most FreeRTOS ports this is done by
  // simply passing higherPriorityTaskWoken into FreeRTOS::yield(), which will
  // test the variables value, and perform the context switch if necessary.
  // Check the documentation for the port in use for port specific instructions.
  FreeRTOS::Kernel::yield();
}

◆ sendFromISR() [2/2]

size_t FreeRTOS::StreamBufferBase::sendFromISR	(	const void *	data,
		const size_t	length
	)		const

inline

Function that calls size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer, const void *pvTxData, size_t xDataLengthBytes, BaseType_t *pxHigherPriorityTaskWoken )

StreamBuffer.hpp

See also: https://www.freertos.org/xStreamBufferSendFromISR.html

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ setTriggerLevel()

bool FreeRTOS::StreamBufferBase::setTriggerLevel ( const size_t triggerLevel = 0 ) const

inline

Function that calls BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel )

StreamBuffer.hpp

See also: https://www.freertos.org/xStreamBufferSetTriggerLevel.html

A stream buffer's trigger level is the number of bytes that must be in the stream buffer before a task that is blocked on the stream buffer to wait for data is moved out of the blocked state. For example, if a task is blocked on a read of an empty stream buffer that has a trigger level of 1 then the task will be unblocked when a single byte is written to the buffer or the task's block time expires. As another example, if a task is blocked on a read of an empty stream buffer that has a trigger level of 10 then the task will not be unblocked until the stream buffer contains at least 10 bytes or the task's block time expires. If a reading task's block time expires before the trigger level is reached then the task will still receive however many bytes are actually available. Setting a trigger level of 0 will result in a trigger level of 1 being used. It is not valid to specify a trigger level that is greater than the buffer size.

Parameters

triggerLevel The new trigger level for the stream buffer.

Return values

true	If triggerLevel was less than or equal to the stream buffer's length then the trigger level was updated.
false	Otherwise.

◆ spacesAvailable()

size_t FreeRTOS::StreamBufferBase::spacesAvailable ( ) const

inline

Function that calls size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer )

StreamBuffer.hpp

See also: https://www.freertos.org/xStreamBufferSpacesAvailable.html

Queries a stream buffer to see how much free space it contains, which is equal to the amount of data that can be sent to the stream buffer before it is full.

Returns: size_t The number of bytes that can be written to the stream buffer before the stream buffer would be full.

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

/home/runner/work/FreeRTOS-Cpp/FreeRTOS-Cpp/FreeRTOS-Cpp/include/FreeRTOS/StreamBuffer.hpp

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ~StreamBufferBase()

Member Function Documentation

◆ bytesAvailable()

◆ isEmpty()

◆ isFull()

◆ isValid()

◆ receive()

◆ receiveFromISR() [1/2]

◆ receiveFromISR() [2/2]

◆ reset()

◆ send()

◆ sendFromISR() [1/2]

◆ sendFromISR() [2/2]

◆ setTriggerLevel()

◆ spacesAvailable()