OSA : Message queues
Intro
The message queue is the most universal tool for data exchange between tasks. A queue allows sending a message before the previous one was received. There are two types of queues in OSA: queues for pointers to messages and queues for simple byte messages.
To use queues in your program you must define constants in OSAcfg.h:
#define OS_ENABLE_QUEUE // To use queues of pointers to messages #define OS_ENABLE_SQUEUE // To use queues of simple byte messages
When these constants are defined, the compiler inserts functions to use queues in your code.
Queues are declared through variables of queue type: OST_QUEUE and OST_SQUEUE:
OST_QUEUE queue; // Declare queue of pointer to messages OST_SQUEUE squeue; // Declare queue of simple byte messages
A variable of OST_QUEUE (or OST_SQUEUE) type contains information about queue size, number of existing messages and a pointer to the message buffer.
A message buffer is an array in RAM where sent messages are stored:
OST_MSG msg_queue[10]; // Buffer for 10 pointers to messages OST_SMSG smsg_queue[15]; // Buffer for 15 simple byte messages
To use a queue we must create it using the service OS_Queue_Create (or OS_Squeue_Create):
OS_Queue_Create(queue, msg_queue, 10); // Create queue of 10 pointers to message. // Sent messages will be stored in msg_queue array
After creating a queue we can send and accept messages through the queue.
Combining queue functions
When it is known that the sizes of OST_MSG and OST_SMSG are the same, we can combine queue functions. This will reduce ROM usage. To do this we need to define a constant in OSAcfg.h:
#define OS_QUEUE_SQUEUE_IDENTICAL
Services
Queue of pointers to message
| Service | Arguments | Description | Properties |
|---|---|---|---|
| Creating | |||
| OS_Queue_Create | (queue, buffer, size) | Create and clear queue |  |
| Sending | |||
| OS_Queue_Send | (queue, message) | Send message via queue. If queue full then wait for free place |   |
| OS_Queue_Send_TO | (queue, message, timeout) | Send message via queue. If queue full then wait for free place. Exit if timeout expired |  |
| OS_Queue_Send_Now | (queue, message) | Send message via queue. If queue is full then oldest message will be dropped |  |
| Checking | |||
bool OS_Queue_Check | (queue) | Check if there is any message in queue | |
bool OS_Queue_IsFull | (queue) | Check if queue of messages is full | |
bool OS_Queue_IsEmpty | (queue) | Check if queue of messages is empty | |
| Waiting | |||
| OS_Queue_Wait | (queue, os_msg_type_var) | Wait message from queue. After accepting message, it will be deleted from queue | |
| OS_Queue_Wait_TO | (queue, os_msg_type_var, timeout) | Wait message from queue. After accepting message, it will be deleted from queue. Exit if timeout expired | |
Queue of simple messages
| Service | Arguments | Description | Properties |
|---|---|---|---|
| Creating | |||
| OS_Squeue_Create | (squeue, buffer, size) | Create and clear queue | |
| Sending | |||
| OS_Squeue_Send | (squeue, smessage) | Send simple message via queue. If queue is full then wait for free slot | |
| OS_Squeue_Send_TO | (squeue, smessage, timeout) | Send message via queue. If queue is full then wait for free slot. Exit if timeout expired. | |
| OS_Squeue_Send_Now | (squeue, smessage) | Send message via queue. If queue is full then oldest message will be dropped | |
| Checking | |||
bool OS_Squeue_Check | (squeue) | Check if there is any simple message in the queue | |
bool OS_Squeue_IsFull | (squeue) | Check if queue of simple messages is full | |
bool OS_Squeue_IsEmpty | (squeue) | Check if queue of simple messages is empty | |
| Waiting | |||
| OS_Squeue_Wait | (squeue, os_smsg_type_var) | Wait for a message from the queue. After accepting the message, it will be deleted from the queue | |
| OS_Squeue_Wait_TO | (squeue, os_smsg_type_var, timeout) | Wait for a message from the queue. After accepting the message, it will be deleted from the queue. Exit if timeout expired | |
