Revision as of 16:37, 22 March 2022

Data Queue

Data Queue Introduction

These are FIFO queues of non-null void pointers ordered by arrival time. Each queue has an associated pending jobs queue, and two associated atomic operations, read and write. A size operation gives the number of pointers on the queue, and the data queue create operation sets the maximum size of the queue.

The read operation returns the first pointer on the queue unless the queue is empty. Unlike many other OS, the job that performs the read operation does not block if the queue is empty. Instead OCEOS provides three options for the read operation to determine what should happen in that case:

In the oceos_dataq_read_continue() option if the queue is empty a null pointer is returned and the job proceeds taking this into account.
In the oceos_dataq_read_restart() or oceos_dataq_read_restart_timeout() options if the queue is empty the job terminates and will restart from its beginning when the queue is written or the timeout occurs.
A job that was started as a result of a timeout does not terminate if it comes to oceos_dataq_read_restart_timeout() and the data queue is still empty, a null pointer is returned to show there was a timeout and the job continues.

A pointer is added to the queue by write. All jobs on the pending list are moved to the ready queue and also removed from the timed actions queue if present.

The pending queue order of jobs with the same priority is preserved in the transfer. The scheduler is then activated and may pre-empt the current executing job.

In case the queue is full, the new entry can be dropped or the oldest entry overwritten, depending on an option chosen when the data queue is created. An appropriate status is returned and a log entry is made if the new entry is dropped.

Data Queue Configuration

API Functions

API Functions
Directive	Description	main	task	IRQ handler
oceos_dataq_create()	Create data queue	*
oceos_dataq_write()	Puts pointer to the data on data queue.		*	*
oceos_dataq_read_continue()	Read data queue next item.		*
oceos_dataq_read_restart()	Read data queue next item.		*
oceos_dataq_read_restart_timeout()	Read data queue next item.		*
oceos_dataq_get_size()	Returns number of items on the data queue		*	*
oceos_dataq_penq_get_size()	Returns number of jobs on the dataq pending job's queue		*	*
oceos_dataq_clear()	Clears data queue and frees tasks on pending queue		*	*

oceos_dataq_create()

oceos_dataq_write()

oceos_dataq_read_continue()

oceos_dataq_read_restart()

oceos_dataq_read_restart_timeout()

oceos_dataq_get_size()

oceos_dataq_penq_get_size()

oceos_dataq_clear()

@@ Line 58: / Line 58: @@
 <span style="color:#1b7ac2">'''Description'''</span><br>
+Create data queue.<br>
+If use_timeout = TRUE, timed actions must be initialized, please see [[OCEOS/oceos timed actions|here]]
 <span style="color:#1b7ac2">'''Prototype'''</span><br>
 <syntaxhighlight lang="C">
+enum DIRECTIVE_STATUS   oceos_dataq_create(
+    dataq_t dataq_id,            // data queue ID
+    U16_t dataq_size,            // data queue size
+    U16_t pen_q_size,            // pending jobs queue size
+    BOOLE_t roll_over,           // whether to roll over when full
+    BOOLE_t use_timeout          // whether timeout is used oceos_dataq_read_restart_timeout
+);
 </syntaxhighlight>
 <span style="color:#1b7ac2">'''Parameters'''</span><br>
 {| class="wikitable"
 |-
-! Parameter !! Description
+! Parameter  !! Description
+|-
+| dataq_id   || Data queue ID
+|-
+| dataq_size || Data queue size
+|-
+| pen_q_size || Pending jobs queue size
+|-
+| roll_over  || Whether to roll over when full
 |-
-|  ||
+| use_timeout|| Whether timeout is used in [[OCEOS/oceos inter-task communication/dataq#oceos_dataq_read_restart_timeout()|oceos_dataq_read_restart_timeout()]]
 |}
 <span style="color:#1b7ac2">'''Returns'''</span><br>
@@ Line 76: / Line 92: @@
 ! enum DIRECTIVE_STATUS !! Description
 |-
-| INCORRECT_STATE || If system Meta pointer is NULL or
+|NOT_CONFIGURED  || System meta pointer is NULL
-                     Init pointer is NULL or
+|-
-                     Start up phase check fail or
+|INCORRECT_STATE || Init meta pointer is NULL
-                     Fixed data checksum failed (check log)
 |-
-| INVALID_NAME    || If Start Sentinel for fixed area is corrupt or
+|INVALID_ID      || Dataq ID is out of range
-                     Start Sentinel for dynamic area is corrupt
 |-
-| INVALID_NUMBER  || If Configuration and actual parameters do not match
+|TOO_MANY        || Dataq ID exceeds dataq number in configuration file
-                     (In configuration file was defined 5 tasks, but created less)
 |-
-| SUCCESSFUL     || If All OK
+|INVALID_NAME    || Dataq ID is not available (already in use)
+|-
+|INVALID_NUMBER  || Dataq_size or pen_q_size is out of range
+|-
+|INVALID_SIZE    || Dataq pen_q_size <= 0
+|-
+|SUCCESSFUL      || All is OK
 |}
 <span style="color:#1b7ac2">'''Example Usage'''</span><br>
 <syntaxhighlight lang="C">
+enum DATAQ_NAME{
+     d_apple,
+    d_orange,
+};
+ enum DIRECTIVE_STATUS status;
+ status = oceos_dataq_create(d_apple, 13, 4, 0, TRUE);
+ if(SUCCESSFUL != status){
+    // Handle ERROR
+  }   // if
   </syntaxhighlight>
 </blockquote>
 ===<span style="color:#0000ff">oceos_dataq_write()</span>===
 <blockquote style="border-left-style: none;">

Difference between revisions of "OCEOS/oceos inter-task communication/dataq"