clear_message_queueT_clear_message_queueClearMessageQueueClearMessageQueue (Operator)

Name

clear_message_queueT_clear_message_queueClearMessageQueueClearMessageQueue — Close a message queue handle and release all associated resources.

Signature

clear_message_queue( : : QueueHandle : )

Description

clear_message_queueclear_message_queueClearMessageQueueClearMessageQueueClearMessageQueue closes a message queue handle QueueHandleQueueHandleQueueHandleQueueHandlequeueHandle that was previously opened with create_message_queuecreate_message_queueCreateMessageQueueCreateMessageQueueCreateMessageQueue. Any resources owned by the message queue, in particular message data queued in the message queue will be released.

Multiple message queue handles can be closed in a single clear_message_queueclear_message_queueClearMessageQueueClearMessageQueueClearMessageQueue call, passing them as a tuple to the QueueHandleQueueHandleQueueHandleQueueHandlequeueHandle parameter.

Attention

The handle(s) must not be used again after being invalidated using clear_message_queueclear_message_queueClearMessageQueueClearMessageQueueClearMessageQueue. Using an invalid handle results in undefined behavior. Operator clear_message_queueclear_message_queueClearMessageQueueClearMessageQueueClearMessageQueue must not be called while the handle is used concurrently from other threads, because this would result in undefined behavior.

Execution Information

Multithreading type: reentrant (runs in parallel with non-exclusive operators).
Multithreading scope: global (may be called from any thread).
Processed without parallelization.

This operator modifies the state of the following input parameter:

QueueHandleQueueHandleQueueHandleQueueHandlequeueHandle

During execution of this operator, access to the value of this parameter must be synchronized if it is used across multiple threads.

Parameters

QueueHandleQueueHandleQueueHandleQueueHandlequeueHandle (input_control, state is modified) message_queue(-array) → (handle)

Message queue handle(s) to be closed.

Number of elements: QueueHandle >= 1

Restriction: QueueHandle != 0

Example (HDevelop)

create_message_queue (ProducerQueue)
create_message_queue (ResultQueue)
* ...

Result

If the message queue handle(s) passed to the operator are valid, clear_message_queueclear_message_queueClearMessageQueueClearMessageQueueClearMessageQueue returns 2 (H_MSG_TRUE). Otherwise an exception is raised. If a tuple of handles is passed and some of them are invalid, clear_message_queueclear_message_queueClearMessageQueueClearMessageQueueClearMessageQueue attempts to clear as many handles from the tuple as possible before reporting the error.