osCreateQueue function
Declaration:
HANDLE osCreateQueue(
  SYSNAME Name,
  UINT8 Mode,
  INDEX MaxCount,
  SIZE MessageSize
);
Parameters:
Name

Name of the object (may be NULL).

Mode

Mode flags (see the description section below)..

MaxCount

The maximal number of messages that can be stored in the queue.

MessageSize

The maximal size of message that can be stored in the queue.

Return value:

The return value is a handle to the created queue object when success or NULL_HANDLE on failure. Use osGetLastError function to obtain extended error information.

Description:

Function creates a queue object.

During queue creation, an optional queue name may be specified. It makes tasks able to open it by osOpenQueue function. The non-used queue should be closed with the osCloseHandle. Queue will be deleted when it is closed by all tasks that opened it. More information you can find in the system objects managementsection.

If all of the osOpen* functions are not used, the system ignores an object name and the code used to name management will be removed. It will reduce final size of the output code. For more information about the names and object opening see the system objects managementsection.

The FIFO (First In, First Out) based queue implementation allows to exchange data between tasks. The data are stored at the 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 in both MessageSize and MaxCount parameters. 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