Coldwave Documentation

Appearance

Message Buffer ​

Lightweight inter-thread message passing.

message buffers can be used to pass variably-sized messages between two threads. the important difference to Message-Queues (aside from the variable size of the messages) is that message buffers should never be used to pass information between more than two threads. There should be one producer and one consumer only.

Sysconfig ​

First HeaderSecond Header
Content CellContent Cell
Content CellContent Cell
cpp
Here is some example code on how to use them.

Functions Overview ​

Name
osMessageBufferId_tosMessageBufferNew(uint32_t bufferSize)
creates a new message buffer
osStatus_tosMessageBufferSend(osMessageBufferId_t mb_id, const void * msg_ptr, size_t msg_len, uint32_t timeout)
send a message to the receiving end of the buffer
osStatus_tosMessageBufferReceive(osMessageBufferId_t mb_id, void * msg_ptr, size_t * msg_len, uint32_t timeout)
wait for a message
osStatus_tosMessageBufferReset(osMessageBufferId_t mb_id)
reset the message buffer. only possible if no resource is blocking on the buffer

Function Details ​

function osMessageBufferNew ​

cpp
osMessageBufferId_t osMessageBufferNew(
    uint32_t bufferSize
)

creates a new message buffer

Parameters:

  • bufferSize maximum size of the total buffer (not just a single message) in bytes.

Return: message buffer ID to be used with send and receive functions.

function osMessageBufferSend ​

cpp
osStatus_t osMessageBufferSend(
    osMessageBufferId_t mb_id,
    const void * msg_ptr,
    size_t msg_len,
    uint32_t timeout
)

send a message to the receiving end of the buffer

Parameters:

  • mb_id message buffer ID as obtained from osMessageBufferNew.
  • msg_ptr pointer to the message. if the message is dynamically allocated, it is up to the recipient to free this memory. If the call fails the caller has to free the memory.
  • msg_len length of the message in bytes.
  • timeout timeout to wait for available buffer space ( in milliseconds )

Return: staus code. osOK if the message was successfully sent.

function osMessageBufferReceive ​

cpp
osStatus_t osMessageBufferReceive(
    osMessageBufferId_t mb_id,
    void * msg_ptr,
    size_t * msg_len,
    uint32_t timeout
)

wait for a message

Parameters:

  • mb_id message buffer ID as obtained from osMessageBufferNew.
  • msg_ptr pointer to the memory where the received message should be put.
  • msg_len size of the memory region that mst_ptr points to.
  • timeout timeout to wait for a message to arrive ( in milliseconds )

Return: staus code. osOK if a message was retrieved

function osMessageBufferReset ​

cpp
osStatus_t osMessageBufferReset(
    osMessageBufferId_t mb_id
)

reset the message buffer. only possible if no resource is blocking on the buffer

Parameters:

  • mb_id message buffer ID as obtained from osMessageBufferNew.

Return: staus code. osOK if reset was successful