The return value is a handle to the newly created queue object upon success, or NULL_HANDLE on failure. Call the osGetLastError function to obtain extended error information.

This function creates a new queue object.

During queue creation, an optional name may be specified, enabling other tasks to open the object using the osOpenQueue function. When the queue is no longer required, it should be closed using osCloseHandle. The queue is deleted only after it has been closed by all tasks that referenced it. Further details can be found in the system objects management section.

If no osOpen* functions are utilized in the application, the system ignores object names and the code associated with name management is excluded from the build. This reduces the final size of the output image. For more information regarding naming conventions and object opening, see the system objects management section.

The queue is implemented as a FIFO (First In, First Out) buffer, facilitating data exchange between tasks. Data is appended to the end of the queue and retrieved from the front. Both the message size and the maximum capacity are fixed at creation via the MessageSize and MaxCount parameters. Upon creation, a memory buffer is allocated; its size is determined by the product of the maximum message size and the maximum message count.

To insert a message into the queue, use the osQueuePost function. The osQueuePend function retrieves and subsequently removes the first message from the queue. To read a message without removing it, use the osQueuePeek function. Standard I/O functions such as osRead and osWrite may also be used. To clear all messages from the queue, call the osClearQueue function.

Queue synchronization is handled in three ways: via a mutex, an auto-reset event, or by disabling interrupts during the data copy operation. The latter is recommended only when transferring small amounts of data. The synchronization method is selected at creation using the OS_IPC_PROTECT_MUTEX, OS_IPC_PROTECT_EVENT, or OS_IPC_PROTECT_INT_CTRL flags. Synchronization via mutex or event is available only when the corresponding constants OS_QUEUE_PROTECT_MUTEX and OS_QUEUE_PROTECT_EVENT are enabled (set to 1).

Attempting to read from an empty queue or write to a full queue will result in an immediate error unless waiting is enabled. Tasks can be configured to block until the operation completes or a timeout occurs. This behavior is enabled by specifying the OS_IPC_WAIT_IF_EMPTY and OS_IPC_WAIT_IF_FULL flags. These features are available only if OS_QUEUE_ALLOW_WAIT_IF_EMPTY and OS_QUEUE_ALLOW_WAIT_IF_FULL are set to 1.

If blocking is enabled, data can be transferred directly between tasks, bypassing the internal buffer. To enable this optimization, use the OS_IPC_DIRECT_READ_WRITE flag. This feature is available only when OS_QUEUE_ALLOW_DIRECT_RW is set to 1.