Available Languages?:

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.

For PIC16, the queue descriptor and message buffer can be allocated in bank0 and bank1 only.

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 Not allowed in interrupt
Sending
OS_Queue_Send (queue, message) Send message via queue. If queue full then wait for free place Allowed only in taskSwitches context
OS_Queue_Send_TO (queue, message, timeout) Send message via queue. If queue full then wait for free place. Exit if timeout expired Allowed only in taskSwitches contextService uses system timer
OS_Queue_Send_Now (queue, message) Send message via queue. If queue is full then oldest message will be dropped Has alternate service for use in ISR (suffix "_I")
Checking
bool
OS_Queue_Check
(queue) Check if there is any message in queue Has alternate service for use in ISR (suffix "_I")
bool
OS_Queue_IsFull
(queue) Check if queue of messages is full Has alternate service for use in ISR (suffix "_I")
bool
OS_Queue_IsEmpty
(queue) Check if queue of messages is empty Has alternate service for use in ISR (suffix "_I")
Waiting
OS_Queue_Wait (queue, os_msg_type_var) Wait message from queue. After accepting message, it will be deleted from queue Allowed only in taskSwitches context
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 Allowed only in taskSwitches contextService uses system timer

Queue of simple messages

Service Arguments Description Properties
Creating
OS_Squeue_Create (squeue, buffer, size) Create and clear queue Not allowed in interrupt
Sending
OS_Squeue_Send (squeue, smessage) Send simple message via queue. If queue is full then wait for free slot Allowed only in taskSwitches context
OS_Squeue_Send_TO (squeue, smessage, timeout) Send message via queue. If queue is full then wait for free slot. Exit if timeout expired. Allowed only in taskSwitches contextService uses system timer
OS_Squeue_Send_Now (squeue, smessage) Send message via queue. If queue is full then oldest message will be dropped Has alternate service for use in ISR (suffix "_I")
Checking
bool
OS_Squeue_Check
(squeue) Check if there is any simple message in the queue Has alternate service for use in ISR (suffix "_I")
bool
OS_Squeue_IsFull
(squeue) Check if queue of simple messages is full Has alternate service for use in ISR (suffix "_I")
bool
OS_Squeue_IsEmpty
(squeue) Check if queue of simple messages is empty Has alternate service for use in ISR (suffix "_I")
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 Allowed only in taskSwitches context
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 Allowed only in taskSwitches contextService uses system timer
 
en/osa/ref/services/mesage_queues.txt · Last modified: 07.10.2010 13:58 (external edit)
 
Creative Commons License Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki