====== 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 ##[[en:osa:ref:appendix:configuration|OSAcfg.h]]##:

<code cpp>
#define OS_ENABLE_QUEUE
                          // To use queues of pointers to messages
#define OS_ENABLE_SQUEUE
                          // To use queues of simple byte messages
</code>

When these constants are defined, the compiler inserts functions to use queues in your code.

Queues are declared through variables of queue type: ##[[en:osa:ref:description:data_types#OST_QUEUE|OST_QUEUE]]## and ##[[en:osa:ref:description:data_types#OST_SQUEUE|OST_SQUEUE]]##:

<code cpp>
OST_QUEUE  queue;    // Declare queue of pointer to messages
OST_SQUEUE squeue;   // Declare queue of simple byte messages
</code>

A variable of ##[[en:osa:ref:description:data_types#OST_QUEUE|OST_QUEUE]]## (or ##[[en:osa:ref:description:data_types#OST_SQUEUE|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:

<code cpp>
OST_MSG   msg_queue[10];         // Buffer for 10 pointers to messages
OST_SMSG  smsg_queue[15];        // Buffer for 15 simple byte messages
</code>

To use a queue we must create it using the service ##[[en:osa:ref:allservices:OS_Queue_Create|OS_Queue_Create]]## (or ##[[en:osa:ref:allservices:OS_Squeue_Create|OS_Squeue_Create]]##):

<code cpp>
    OS_Queue_Create(queue, msg_queue, 10);  // Create queue of 10 pointers to message.
                                            // Sent messages will be stored in msg_queue array
</code>

After creating a queue we can send and accept messages through the queue.

<note>
For **PIC16**, the queue descriptor and message buffer can be allocated in **bank0** and **bank1** only.
</note>

==== Combining queue functions ====

When it is known that the sizes of ##[[en:osa:ref:description:data_types#OST_MSG|OST_MSG]]## and ##[[en:osa:ref:description:data_types#OST_SMSG|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 ##[[en:osa:ref:appendix:configuration|OSAcfg.h]]##:

<code cpp>
#define OS_QUEUE_SQUEUE_IDENTICAL
</code>

~~UP~~

===== Services =====



==== Queue of pointers to message ====

^  Service  ^  Arguments  ^  Description  ^  Properties  ^
| **Creating**    ||||
| ##[[en:osa:ref:allservices:OS_Queue_Create|OS_Queue_Create]]##  |  ''(queue, buffer, size)''  | Create and clear queue  | {{osa:ref:attr_call_not_int.png|Not allowed in interrupt}}  |
| **Sending**     ||||
| ##[[en:osa:ref:allservices:OS_Queue_Send|OS_Queue_Send]]##  |  ''(queue, message)''  | Send message via queue. If queue full then wait for free place  | {{osa:ref:attr_call_task.png|Allowed only in task}}{{osa:ref:attr_call_ct_sw.png|Switches context}}  |
| ##[[en:osa:ref:allservices:OS_Queue_Send_TO|OS_Queue_Send_TO]]##  |  ''(queue, message, timeout)''  | Send message via queue. If queue full then wait for free place. Exit if timeout expired  | {{osa:ref:attr_call_task.png|Allowed only in task}}{{osa:ref:attr_call_ct_sw.png|Switches context}}{{osa:ref:attr_call_to.png|Service uses system timer}}  |
| ##[[en:osa:ref:allservices:OS_Queue_Send_Now|OS_Queue_Send_Now]]##  |  ''(queue, message)''  | Send message via queue. If queue is full then oldest message will be dropped  | {{osa:ref:attr_call_can_int.png|Has alternate service for use in ISR (suffix "_I")}}  |
| **Checking**    ||||
| ''bool ''\\ ##[[en:osa:ref:allservices:OS_Queue_Check|OS_Queue_Check]]##  |  ''(queue)''  | Check if there is any message in queue  | {{osa:ref:attr_call_can_int.png|Has alternate service for use in ISR (suffix "_I")}}  |
| ''bool ''\\ ##[[en:osa:ref:allservices:OS_Queue_IsFull|OS_Queue_IsFull]]##  |  ''(queue)''  | Check if queue of messages is full  | {{osa:ref:attr_call_can_int.png|Has alternate service for use in ISR (suffix "_I")}}  |
| ''bool ''\\ ##[[en:osa:ref:allservices:OS_Queue_IsEmpty|OS_Queue_IsEmpty]]##  |  ''(queue)''  | Check if queue of messages is empty  | {{osa:ref:attr_call_can_int.png|Has alternate service for use in ISR (suffix "_I")}}  |
| **Waiting**     ||||
| ##[[en:osa:ref:allservices:OS_Queue_Wait|OS_Queue_Wait]]##  |  ''(queue, os_msg_type_var)''  | Wait message from queue. After accepting message, it will be deleted from queue  | {{osa:ref:attr_call_task.png|Allowed only in task}}{{osa:ref:attr_call_ct_sw.png|Switches context}}  |
| ##[[en:osa:ref:allservices:OS_Queue_Wait_TO|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  | {{osa:ref:attr_call_task.png|Allowed only in task}}{{osa:ref:attr_call_ct_sw.png|Switches context}}{{osa:ref:attr_call_to.png|Service uses system timer}}  |


~~UP~~

==== Queue of simple messages ====

^  Service  ^  Arguments  ^  Description  ^  Properties  ^
| **Creating**    ||||
| ##[[en:osa:ref:allservices:OS_Squeue_Create|OS_Squeue_Create]]##  |  ''(squeue, buffer, size)''  | Create and clear queue  | {{osa:ref:attr_call_not_int.png|Not allowed in interrupt}}  |
| **Sending**     ||||
| ##[[en:osa:ref:allservices:OS_Squeue_Send|OS_Squeue_Send]]##  |  ''(squeue, smessage)''  | Send simple message via queue. If queue is full then wait for free slot  | {{osa:ref:attr_call_task.png|Allowed only in task}}{{osa:ref:attr_call_ct_sw.png|Switches context}}  |
| ##[[en:osa:ref:allservices:OS_Squeue_Send_TO|OS_Squeue_Send_TO]]##  |  ''(squeue, smessage, timeout)''  | Send message via queue. If queue is full then wait for free slot. Exit if timeout expired.  | {{osa:ref:attr_call_task.png|Allowed only in task}}{{osa:ref:attr_call_ct_sw.png|Switches context}}{{osa:ref:attr_call_to.png|Service uses system timer}}  |
| ##[[en:osa:ref:allservices:OS_Squeue_Send_Now|OS_Squeue_Send_Now]]##  |  ''(squeue, smessage)''  | Send message via queue. If queue is full then oldest message will be dropped  | {{osa:ref:attr_call_can_int.png|Has alternate service for use in ISR (suffix "_I")}}  |
| **Checking**    ||||
| ''bool ''\\ ##[[en:osa:ref:allservices:OS_Squeue_Check|OS_Squeue_Check]]##  |  ''(squeue)''  | Check if there is any simple message in the queue  | {{osa:ref:attr_call_can_int.png|Has alternate service for use in ISR (suffix "_I")}}  |
| ''bool ''\\ ##[[en:osa:ref:allservices:OS_Squeue_IsFull|OS_Squeue_IsFull]]##  |  ''(squeue)''  | Check if queue of simple messages is full  | {{osa:ref:attr_call_can_int.png|Has alternate service for use in ISR (suffix "_I")}}  |
| ''bool ''\\ ##[[en:osa:ref:allservices:OS_Squeue_IsEmpty|OS_Squeue_IsEmpty]]##  |  ''(squeue)''  | Check if queue of simple messages is empty  | {{osa:ref:attr_call_can_int.png|Has alternate service for use in ISR (suffix "_I")}}  |
| **Waiting**     ||||
| ##[[en:osa:ref:allservices:OS_Squeue_Wait|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  | {{osa:ref:attr_call_task.png|Allowed only in task}}{{osa:ref:attr_call_ct_sw.png|Switches context}}  |
| ##[[en:osa:ref:allservices:OS_Squeue_Wait_TO|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  | {{osa:ref:attr_call_task.png|Allowed only in task}}{{osa:ref:attr_call_ct_sw.png|Switches context}}{{osa:ref:attr_call_to.png|Service uses system timer}}  |


~~UP~~