create_message_queuecreate_message_queueCreateMessageQueuecreate_message_queueCreateMessageQueueCreateMessageQueue (Operator)

Name

create_message_queuecreate_message_queueCreateMessageQueuecreate_message_queueCreateMessageQueueCreateMessageQueue — Create a new empty message queue.

Signature

create_message_queue( : : : QueueHandle)

create_message_queuecreate_message_queueCreateMessageQueuecreate_message_queueCreateMessageQueueCreateMessageQueue creates a new empty message queue. The output parameter QueueHandleQueueHandleQueueHandleQueueHandleQueueHandlequeueHandle is a handle to the newly created message queue and is used to identify the queue in any subsequent operator calls using the queue.

The message queues are designed as FIFO pipes delivering arbitrary sets of data safely among different threads. The queue access is internally fully synchronized, no explicit locking is required from the application. The data is traveling through the queue in so called messages (see create_messagecreate_messageCreateMessagecreate_messageCreateMessageCreateMessage).

Multiple producer threads can append data simultaneously (enqueue_messageenqueue_messageEnqueueMessageenqueue_messageEnqueueMessageEnqueueMessage) while multiple consumer threads are simultaneously retrieving the data again (dequeue_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage). Multiple messages can be enqueued together using a single enqueue_messageenqueue_messageEnqueueMessageenqueue_messageEnqueueMessageEnqueueMessage operation. In such case, those messages will travel together through the queue and will be delivered through a single dequeue_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage call.

Any messages sent to the queue are deeply copied (including the tuples and objects stored in the messages) by the enqueue_messageenqueue_messageEnqueueMessageenqueue_messageEnqueueMessageEnqueueMessage operation. The original message(s) can thus be immediately reused after the enqueue_messageenqueue_messageEnqueueMessageenqueue_messageEnqueueMessageEnqueueMessage call without affecting the enqueued copy.

When the message queue is no more needed, all associated resources, in particular the yet enqueued messages with all data they carry, should be released using clear_message_queueclear_message_queueClearMessageQueueclear_message_queueClearMessageQueueClearMessageQueue. Depending on the context, releasing any threads waiting for the queue data and flushing the queue contents might be required using set_message_queue_paramset_message_queue_paramSetMessageQueueParamset_message_queue_paramSetMessageQueueParamSetMessageQueueParam before clearing the queue.

Parallelization

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

Parameters

QueueHandleQueueHandleQueueHandleQueueHandleQueueHandlequeueHandle (output_control) message_queue → (integer)

Handle of the newly created message queue.

Number of elements: QueueHandle == 1

Assertion: QueueHandle != 0

Example (HDevelop)

create_message_queue (ProducerQueue)
create_message_queue (ResultQueue)
* ...
clear_message_queue ([ProducerQueue,ResultQueue])

Result

Returns 2 (H_MSG_TRUE) unless a resource allocation error occurs. Otherwise an exception is raised.

Possible Successors

enqueue_messageenqueue_messageEnqueueMessageenqueue_messageEnqueueMessageEnqueueMessage, dequeue_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage

clear_message_queueclear_message_queueClearMessageQueueclear_message_queueClearMessageQueueClearMessageQueue, enqueue_messageenqueue_messageEnqueueMessageenqueue_messageEnqueueMessageEnqueueMessage, dequeue_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage, set_message_queue_paramset_message_queue_paramSetMessageQueueParamset_message_queue_paramSetMessageQueueParamSetMessageQueueParam, get_message_queue_paramget_message_queue_paramGetMessageQueueParamget_message_queue_paramGetMessageQueueParamGetMessageQueueParam, create_messagecreate_messageCreateMessagecreate_messageCreateMessageCreateMessage, clear_messageclear_messageClearMessageclear_messageClearMessageClearMessage, set_message_tupleset_message_tupleSetMessageTupleset_message_tupleSetMessageTupleSetMessageTuple, get_message_tupleget_message_tupleGetMessageTupleget_message_tupleGetMessageTupleGetMessageTuple, set_message_objset_message_objSetMessageObjset_message_objSetMessageObjSetMessageObj, get_message_objget_message_objGetMessageObjget_message_objGetMessageObjGetMessageObj

Module

Foundation

Operators