OCEOS/oceos inter-task communication/dataq
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.
Note
If timeouts are used with data queues the hardware specific timer initialization and handling must be set up by the developer please see here.
Data Queue Configuration
User must define NUMBER_OF_DATAQS. If NUMBER_OF_DATAQS is zero, data queues are not used. The example can be found in OCEOS demo projects.
User must create defined number of data queues before calling oceos_init_finish()#define NUMBER_OF_DATAQS 2 /* * Create the application configuration structure */ struct application_configuration app_config = {0}; app_config.number_of_data_queues = NUMBER_OF_DATAQS;
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()
Header File
dataq.h
Description
Prototype
Parameters
Parameter Description Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description INCORRECT_STATE If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL If All OK Example Usage
oceos_dataq_write()
Header File
dataq.h
Description
Prototype
Parameters
Parameter Description Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description INCORRECT_STATE If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL If All OK Example Usage
oceos_dataq_read_continue()
Header File
dataq.h
Description
Prototype
Parameters
Parameter Description Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description INCORRECT_STATE If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL If All OK Example Usage
oceos_dataq_read_restart()
Header File
dataq.h
Description
Prototype
Parameters
Parameter Description Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description INCORRECT_STATE If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL If All OK Example Usage
oceos_init_finish()
Header File
dataq.h
Description
Prototype
Parameters
Parameter Description Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description INCORRECT_STATE If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL If All OK Example Usage
oceos_init_finish()
Header File
dataq.h
Description
Prototype
Parameters
Parameter Description Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description INCORRECT_STATE If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL If All OK Example Usage
oceos_init_finish()
Header File
dataq.h
Description
Prototype
Parameters
Parameter Description Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description INCORRECT_STATE If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL If All OK Example Usage
oceos_init_finish()
Header File
dataq.h
Description
Prototype
Parameters
Parameter Description Returns
This function returns enum DIRECTIVE_STATUS.
enum DIRECTIVE_STATUS Description INCORRECT_STATE If system Meta pointer is NULL or Init pointer is NULL or Start up phase check fail or Fixed data checksum failed (check log)
INVALID_NAME If Start Sentinel for fixed area is corrupt or Start Sentinel for dynamic area is corrupt
INVALID_NUMBER If Configuration and actual parameters do not match (In configuration file was defined 5 tasks, but created less)
SUCCESSFUL If All OK Example Usage