Base class that provides the standard message buffer interface to FreeRTOS::MessageBuffer and FreeRTOS::StaticMessageBuffer. More...

#include <FreeRTOS/MessageBuffer.hpp>

Inheritance diagram for FreeRTOS::MessageBufferBase:

[legend]

Public Member Functions
	MessageBufferBase (const MessageBufferBase &)=delete

MessageBufferBase &	operator= (const MessageBufferBase &)=delete

bool	isValid () const
	Function that checks if the underlying message buffer handle is not NULL. This should be used to ensure a message 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 xMessageBufferSend( MessageBufferHandle_t xMessageBuffer, 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 xMessageBufferSendFromISR( MessageBufferHandle_t xMessageBuffer, 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 xMessageBufferSendFromISR( MessageBufferHandle_t xMessageBuffer, 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 xMessageBufferReceive( MessageBufferHandle_t xMessageBuffer, 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 xMessageBufferReceiveFromISR( MessageBufferHandle_t xMessageBuffer, void pvRxData, size_t xBufferLengthBytes, BaseType_t pxHigherPriorityTaskWoken )`

size_t	receiveFromISR (void *buffer, const size_t bufferLength) const
	Function that calls `size_t xMessageBufferReceiveFromISR( MessageBufferHandle_t xMessageBuffer, void pvRxData, size_t xBufferLengthBytes, BaseType_t pxHigherPriorityTaskWoken )`

size_t	spacesAvailable () const
	Function that calls `size_t xMessageBufferSpacesAvailable( MessageBufferHandle_t xMessageBuffer )`

bool	reset () const
	Function that calls `BaseType_t xMessageBufferReset( MessageBufferHandle_t xMessageBuffer )`

bool	isEmpty () const
	Function that calls `BaseType_t xMessageBufferIsEmpty( MessageBufferHandle_t xMessageBuffer )`

bool	isFull () const
	Function that calls `BaseType_t xMessageBufferIsFull( MessageBufferHandle_t xMessageBuffer )`

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
	~MessageBufferBase ()
	Destroy the MessageBufferBase object by calling `void vMessageBufferDelete( MessageBufferHandle_t xMessageBuffer )`

	MessageBufferBase (MessageBufferBase &&) noexcept=default

MessageBufferBase &	operator= (MessageBufferBase &&) noexcept=default

Private Attributes
MessageBufferHandle_t	handle = NULL

Friends
class	MessageBuffer

template<size_t >
class	StaticMessageBuffer

Detailed Description

Base class that provides the standard message buffer interface to FreeRTOS::MessageBuffer and FreeRTOS::StaticMessageBuffer.

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

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

◆ ~MessageBufferBase()

FreeRTOS::MessageBufferBase::~MessageBufferBase ( )

inlineprivate

Destroy the MessageBufferBase object by calling void vMessageBufferDelete( MessageBufferHandle_t xMessageBuffer )

MessageBuffer.hpp

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

Delete a queue - freeing all the memory allocated for storing of items placed on the queue.

Member Function Documentation

◆ isEmpty()

bool FreeRTOS::MessageBufferBase::isEmpty ( ) const

inline

Function that calls BaseType_t xMessageBufferIsEmpty( MessageBufferHandle_t xMessageBuffer )

MessageBuffer.hpp

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

Queries a message buffer to see if it is empty. A message buffer is empty if it does not contain any messages.

Return values

true	If the message buffer is empty.
false	Otherwise.

◆ isFull()

bool FreeRTOS::MessageBufferBase::isFull ( ) const

inline

Function that calls BaseType_t xMessageBufferIsFull( MessageBufferHandle_t xMessageBuffer )

MessageBuffer.hpp

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

Queries a message buffer to see if it is full. A message buffer is full if it cannot accept any more messages, of any size, until space is made available by a message being removed from the message buffer.

Return values

true	If the message buffer is full.
false	Otherwise.

◆ isValid()

bool FreeRTOS::MessageBufferBase::isValid ( ) const

inline

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

MessageBuffer.hpp

Return values

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

◆ receive()

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

inline

Function that calls size_t xMessageBufferReceive( MessageBufferHandle_t xMessageBuffer, void *pvRxData, size_t xBufferLengthBytes, TickType_t xTicksToWait )

MessageBuffer.hpp

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

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

Parameters

buffer	A pointer to the buffer into which the received message is to be copied.
bufferLength	The length of the buffer pointed to by the buffer parameter. This sets the maximum length of the message that can be received. If bufferLength is too small to hold the next message then the message will be left in the message buffer and 0 will be returned.
ticksToWait	The maximum amount of time the task should remain in the Blocked state to wait for a message, should the message buffer be empty. receive() will return immediately if ticksToWait is zero and the message buffer is empty. 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. Tasks do not use any CPU time when they are in the Blocked state.

Returns: size_t The length, in bytes, of the message read from the message buffer, if any. If receive() times out before a message became available then zero is returned. If the length of the message is greater than bufferLength then the message will be left in the message buffer and zero is returned.

Example Usage

#include <FreeRTOS/MessageBuffer.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  MyTask() : messageBuffer(100) {}
  void taskFunction() final;
  FreeRTOS::MessageBuffer messageBuffer;
};
 
void MyTask::taskFunction() {
  uint8_t ucRxData[20];
  size_t xReceivedBytes;
 
  // Receive the next message from the message buffer.  Wait in the Blocked
  // state (so not using any CPU processing time) for a maximum of 100ms for a
  // message to become available.
  xReceivedBytes = messageBuffer.receive((void*)ucRxData, sizeof(ucRxData),
                                         pdMS_TO_TICKS(20));
 
  if (xReceivedBytes > 0) {
    // A ucRxData contains a message that is xReceivedBytes long.  Process the
    // message here...
  }
 
  // Rest of task code.
}

◆ receiveFromISR() [1/2]

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

inline

Function that calls size_t xMessageBufferReceiveFromISR( MessageBufferHandle_t xMessageBuffer, void *pvRxData, size_t xBufferLengthBytes, BaseType_t *pxHigherPriorityTaskWoken )

MessageBuffer.hpp

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

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

Parameters

higherPriorityTaskWoken	It is possible that a message 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 message is to be copied.
bufferLength	The length of the buffer pointed to by the buffer parameter. This sets the maximum length of the message that can be received. If bufferLength is too small to hold the next message then the message will be left in the message buffer and 0 will be returned.

Returns: size_t The length, in bytes, of the message read from the message buffer, if any.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/MessageBuffer.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::StaticTask<configMINIMAL_STACK_SIZE> {
 public:
  MyTask() : messageBuffer(100) {}
  void taskFunction() final;
  FreeRTOS::MessageBuffer messageBuffer;
};
 
MyTask task;
 
void anInterruptServiceRoutine() {
  uint8_t ucRxData[20];
  size_t xReceivedBytes;
  bool higherPriorityTaskWoken = false;
 
  // Receive the next message from the message buffer.
  xReceivedBytes = task.messageBuffer.receiveFromISR(
      higherPriorityTaskWoken, (void*)ucRxData, sizeof(ucRxData));
 
  if (xReceivedBytes > 0) {
    // ucRxData contains a message that is xReceivedBytes long.  Process the
    // message 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::MessageBufferBase::receiveFromISR	(	void *	buffer,
		const size_t	bufferLength
	)		const

inline

Function that calls size_t xMessageBufferReceiveFromISR( MessageBufferHandle_t xMessageBuffer, void *pvRxData, size_t xBufferLengthBytes, BaseType_t *pxHigherPriorityTaskWoken )

MessageBuffer.hpp

See also: https://www.freertos.org/xMessageBufferReceiveFromISR.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::MessageBufferBase::reset ( ) const

inline

Function that calls BaseType_t xMessageBufferReset( MessageBufferHandle_t xMessageBuffer )

MessageBuffer.hpp

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

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

Return values

true	If the message buffer is reset.
false	If there was a task blocked waiting to send to or read from the message buffer then the message buffer will not be reset.

◆ send()

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

inline

Function that calls size_t xMessageBufferSend( MessageBufferHandle_t xMessageBuffer, const void *pvTxData, size_t xDataLengthBytes, TickType_t xTicksToWait )

MessageBuffer.hpp

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

Sends a discrete message to the message buffer. The message can be any length that fits within the buffer's free space, and is copied into the buffer.

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

Parameters

data	A pointer to the message that is to be copied into the message buffer.
length	The length of the message. That is, the number of bytes to copy from data into the message buffer. When a message is written to the message buffer an additional sizeof( size_t ) bytes are also written to store the message's length. sizeof( size_t ) is typically 4 bytes on a 32-bit architecture, so on most 32-bit architecture setting length to 20 will reduce the free space in the message buffer by 24 bytes (20 bytes of message data and 4 bytes to hold the message length).
ticksToWait	The maximum amount of time the calling task should remain in the Blocked state to wait for enough space to become available in the message buffer, should the message buffer have insufficient space when send() is called. The calling task will never block 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. Tasks do not use any CPU time when they are in the Blocked state.

Returns: size_t The number of bytes written to the message buffer. If the call to send() times out before there was enough space to write the message into the message buffer then zero is returned. If the call did not time out then length is returned.

Example Usage

#include <FreeRTOS/MessageBuffer.hpp>
#include <FreeRTOS/Task.hpp>
#include <cstring>
 
class MyTask : public FreeRTOS::Task {
 public:
  MyTask() : messageBuffer(100) {}
  void taskFunction() final;
  FreeRTOS::MessageBuffer messageBuffer;
};
 
void MyTask::taskFunction() {
  size_t xBytesSent;
  uint8_t ucArrayToSend[] = {0, 1, 2, 3};
  char const *pcStringToSend = "String to send";
 
  // Send an array to the message buffer, blocking for a maximum of 100ms to
  // wait for enough space to be available in the message buffer.
  xBytesSent = messageBuffer.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.
  }
 
  // Send the string to the message buffer.  Return immediately if there is not
  // enough space in the buffer.
  xBytesSent = messageBuffer.send(pcStringToSend, strlen(pcStringToSend), 0);
 
  if (xBytesSent != strlen(pcStringToSend)) {
    // The string could not be added to the message buffer because there was not
    // enough free space in the buffer.
  }
 
  // Rest of task code.
}

◆ sendFromISR() [1/2]

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

inline

Function that calls size_t xMessageBufferSendFromISR( MessageBufferHandle_t xMessageBuffer, const void *pvTxData, size_t xDataLengthBytes, BaseType_t *pxHigherPriorityTaskWoken )

MessageBuffer.hpp

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

Interrupt safe version of the API function that sends a discrete message to the message buffer. The message can be any length that fits within the buffer's free space, and is copied into the buffer.

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

Parameters

higherPriorityTaskWoken	It is possible that a message 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 code example below for an example.
data	A pointer to the message that is to be copied into the message buffer.
length	The length of the message. That is, the number of bytes to copy from data into the message buffer. When a message is written to the message buffer an additional sizeof( size_t ) bytes are also written to store the message's length. sizeof( size_t ) is typically 4 bytes on a 32-bit architecture, so on most 32-bit architecture setting length to 20 will reduce the free space in the message buffer by 24 bytes (20 bytes of message data and 4 bytes to hold the message length).

Returns: size_t The number of bytes actually written to the message buffer. If the message buffer didn't have enough free space for the message to be stored then 0 is returned, otherwise length is returned.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/MessageBuffer.hpp>
#include <FreeRTOS/Task.hpp>
#include <cstring>
 
class MyTask : public FreeRTOS::StaticTask<configMINIMAL_STACK_SIZE> {
 public:
  MyTask() : messageBuffer(100) {}
  void taskFunction() final;
  FreeRTOS::MessageBuffer messageBuffer;
};
 
MyTask task;
 
void anInterruptServiceRoutine() {
  char const *pcStringToSend = "String to send";
  bool higherPriorityTaskWoken = false;
 
  // Attempt to send the string to the message buffer.
  size_t xBytesSent = task.messageBuffer.sendFromISR(
      higherPriorityTaskWoken, pcStringToSend, sizeof(pcStringToSend));
 
  if (xBytesSent != sizeof(pcStringToSend)) {
    // The string could not be added to the message buffer because there was not
    // enough free space in the buffer.
  }
 
  // 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::MessageBufferBase::sendFromISR	(	const void *	data,
		const size_t	length
	)		const

inline

Function that calls size_t xMessageBufferSendFromISR( MessageBufferHandle_t xMessageBuffer, const void *pvTxData, size_t xDataLengthBytes, BaseType_t *pxHigherPriorityTaskWoken )

MessageBuffer.hpp

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

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

◆ spacesAvailable()

size_t FreeRTOS::MessageBufferBase::spacesAvailable ( ) const

inline

Function that calls size_t xMessageBufferSpacesAvailable( MessageBufferHandle_t xMessageBuffer )

MessageBuffer.hpp

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

Queries a message buffer to see how much free space it contains, which is equal to the amount of data that can be sent to the message buffer before it is full. The returned value is 4 bytes larger than the maximum message size that can be sent to the message buffer.

Returns: size_t The number of bytes that can be written to the message buffer before the message buffer would be full. When a message is written to the message buffer an additional sizeof( size_t ) bytes are also written to store the message's length. sizeof( size_t ) is typically 4 bytes on a 32-bit architecture, so if spacesAvailable() returns 10, then the size of the largest message that can be written to the message buffer is 6 bytes.

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

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

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ~MessageBufferBase()

Member Function Documentation

◆ isEmpty()

◆ isFull()

◆ isValid()

◆ receive()

◆ receiveFromISR() [1/2]

◆ receiveFromISR() [2/2]

◆ reset()

◆ send()

◆ sendFromISR() [1/2]

◆ sendFromISR() [2/2]

◆ spacesAvailable()