Queue objects

The FIFO (First In, First Out) based queue implementation allows to exchange data between tasks. The data are stored at end of queue and read from its beginning. The message size and the maximal number of messages that can be stored in the queue is restricted and determined during queue object creation.

Queue creation and deletion

The function osCreateQueue creates a queue object. The queue can be created before system start, from an interrupt handler or by a task. During queue creation, an optional queue name may be specified. It makes tasks able to open it by osOpenQueue function. During queue creation and opening, its handle is returned. The handle is assigned by the system and it is used to discern the system objects. All operations performed on the queue except to specify its handle. The non-used queue should be closed with the osCloseHandle. Queue will be deleted when it will be closed by all tasks that opened it. More information you can find in the system objects management section.

When queues are not used, the OS_USE_QUEUE constant may be set to 0, to reduce the output code.

Using a queue object

The maximal size and the number of messages that can be stored by queue are determined during its creation. When queue is created, it is allocated a memory buffer. Its size depends on the maximal size and the number of messages and is a multiplication of both values.

To insert the message into a queue the osQueuePost function should be called. An osQueuePend function allows to read and later to remove the first message from the queue. To read the message without removing it, the osQueuePeek function should be used. Read and write operations can be performed also by system functions, such as osRead and osWrite. To delete all messages from queue it should be called the osClearQueuefunction.

Access to queue synchronization is realized in three ways. It may be protected by mutex, auto-reset event, or by interrupt disabling for data copy time. The last way can be realized only when small portions of data are transferred to or from a queue. The way of synchronization is chosen during queue creation by using OS_IPC_PROTECT_MUTEX, OS_IPC_PROTECT_EVENT or OS_IPC_PROTECT_INT_CTRL mode flags. Synchronization mode by mutex or auto-reset event is available only when corresponding constants OS_QUEUE_PROTECT_MUTEX and OS_QUEUE_PROTECT_EVENT are set to 1.

When read operation is performed on the queue with an empty buffer, or the write operation is carried out when the buffer is full, the operation will be finished with an error. The task may also be waiting for a read or write operation completion. The task is resumed when data will be successfully transferred, or specified timeout interval elapses. It is realized by the appropriate specifying mode flags OS_IPC_WAIT_IF_EMPTY and OS_IPC_WAIT_IF_FULLduring queue creation. These operations are available only when the corresponding constants OS_QUEUE_ALLOW_WAIT_IF_EMPTY and OS_QUEUE_ALLOW_WAIT_IF_FULL are set to 1.

When the wait for operation completion is enabled, the data can be sending directly from one task to another, without storing data in the buffer. To enable this feature, it should be set OS_IPC_DIRECT_READ_WRITE mode flag and it is only available when OS_QUEUE_ALLOW_DIRECT_RW is set to 1.

SpaceShadow documentation