CMSIS-RTOS
Version 1.03
Real-Time Operating System: API and RTX Reference Implementation.
|
Exchange messages between threads in a FIFO-like operation. More...
Macros | |
#define | osFeature_MessageQ 1 |
Message Queues: 1=available, 0=not available. More... | |
#define | osMessageQDef(name, queue_sz, type) |
Create a Message Queue Definition. More... | |
#define | osMessageQ(name) &os_messageQ_def_##name |
Access a Message Queue Definition. More... | |
Functions | |
osMessageQId | osMessageCreate (const osMessageQDef_t *queue_def, osThreadId thread_id) |
Create and Initialize a Message Queue. More... | |
osStatus | osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec) |
Put a Message to a Queue. More... | |
osEvent | osMessageGet (osMessageQId queue_id, uint32_t millisec) |
Get a Message or Wait for a Message from a Queue. More... | |
Message passing is another basic communication model between threads. In the message passing model, one thread sends data explicitly, while another thread receives it. The operation is more like some kind of I/O rather than a direct access to information to be shared. In CMSIS-RTOS, this mechanism is called s message queue. The data is passed from one thread to another in a FIFO-like operation. Using message queue functions, you can control, send, receive, or wait for messages. The data to be passed can be of integer or pointer type:
Compared to a Memory Pool, message queues are less efficient in general, but solve a broader range of problems. Sometimes, threads do not have a common address space or the use of shared memory raises problems, such as mutual exclusion.
Follow these steps to create and use a message queue:
#define osFeature_MessageQ 1 |
A CMSIS-RTOS implementation may support message queues.
CMSIS-RTOS RTX Setting: osFeature_MessageQ is 1
#define osMessageQ | ( | name | ) | &os_messageQ_def_##name |
Access to the message queue definition for the function osMessageCreate.
name | name of the queue |
#define osMessageQDef | ( | name, | |
queue_sz, | |||
type | |||
) |
Define the attributes of a message queue created by the function osMessageCreate using osMessageQ.
name | name of the queue. |
queue_sz | maximum number of messages in the queue. |
type | data type of a single message element (for debugger). |
osMessageQId osMessageCreate | ( | const osMessageQDef_t * | queue_def, |
osThreadId | thread_id | ||
) |
[in] | queue_def | queue definition referenced with osMessageQ. |
[in] | thread_id | thread ID (obtained by osThreadCreate or osThreadGetId) or NULL. |
Create and initialize a message queue. The parameter thread_id registers the receiving thread for a message and is needed for the general osWait function to deliver the message.
Code Example
osEvent osMessageGet | ( | osMessageQId | queue_id, |
uint32_t | millisec | ||
) |
[in] | queue_id | message queue ID obtained with osMessageCreate. |
[in] | millisec | Timout Value or 0 in case of no time-out. |
Suspend the execution of the current RUNNING thread until a message arrives. When a message is already in the queue, the function returns instantly with the message information.
The argument millisec specifies how long the system waits for a message to become available. While the system waits the thread that is calling this function is put into the state WAITING. The millisec timeout value can have the following values:
osStatus osMessagePut | ( | osMessageQId | queue_id, |
uint32_t | info, | ||
uint32_t | millisec | ||
) |
[in] | queue_id | message queue ID obtained with osMessageCreate. |
[in] | info | message information. |
[in] | millisec | Timout Value or 0 in case of no time-out. |
Put the message info in a message queue specified by queue_id.
When the message queue is full, the system retries for a specified time with millisec. While the system retries the thread that is calling this function is put into the state WAITING. The millisec timeout can have the following values: