enqueue_messageT_enqueue_messageEnqueueMessageEnqueueMessage (Operator)

Name

enqueue_messageT_enqueue_messageEnqueueMessageEnqueueMessage — Enqueue one or more messages to the message queue.

Signature

Description

enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessage enqueues one or more messages to the message queue denoted by the QueueHandleQueueHandleQueueHandleQueueHandlequeueHandle parameter. The enqueued messages can be retrieved from the queue by any thread using dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessage.

The messages (see create_messagecreate_messageCreateMessageCreateMessageCreateMessage) to be enqueued are specified in the MessageHandleMessageHandleMessageHandleMessageHandlemessageHandle parameter which accepts a single handle as well as tuple of handles. When enqueuing multiple handles together in a single enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessage call, they are delivered again together through a single dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessage call.

Multiple producer (enqueuing) threads and multiple consumer (dequeuing) threads can share the same queue at a time. The messages are delivered in FIFO (first-in first-out) order. Every message is delivered only once, even if multiple consumer threads are using the queue.

The queue access is internally fully synchronized, no external locking is required. If the queue is empty and there is at least one consumer thread waiting for the message data in dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessage, one of those threads is woken up by a successful enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessage call and the enqueued message data are immediately delivered. Otherwise the message data is apended to the queue asynchronously, to be delivered as soon as a consumer thread is ready to dequeue the message data again.

All the enqueued messages (MessageHandleMessageHandleMessageHandleMessageHandlemessageHandle) are copied by the enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessage operation. The original message(s) can thus be immediately reused after the enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessage call without affecting the enqueued copy.

Operator parameters GenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue are reserved in the operator's interface for future use, currently no generic parameters are supported.

If, after the operation, the queue would hold a larger number of messages than the maximum number specified with parameter value 'max_message_num'"max_message_num""max_message_num""max_message_num""max_message_num" of operator set_message_queue_paramset_message_queue_paramSetMessageQueueParamSetMessageQueueParamSetMessageQueueParam, the call would fail with H_ERR_MQOVL.

Execution Information

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

Parameters

Example (HDevelop)

	create_message_queue (Queue)
* ...
create_message (Message)
set_message_tuple (Message, 'mixed_tuple', ['The answer', 42])
enqueue_message (Queue, Message, [], [])
clear_message (Message)

Result

If the operation succeeds, enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessage returns 2 (H_MSG_TRUE). Otherwise an exception is raised. Possible error conditions include invalid parameters or resource allocation error.

Possible Predecessors

set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleSetMessageTuple, set_message_objset_message_objSetMessageObjSetMessageObjSetMessageObj

See also

create_message_queuecreate_message_queueCreateMessageQueueCreateMessageQueueCreateMessageQueue, clear_message_queueclear_message_queueClearMessageQueueClearMessageQueueClearMessageQueue, dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessage, set_message_queue_paramset_message_queue_paramSetMessageQueueParamSetMessageQueueParamSetMessageQueueParam, get_message_queue_paramget_message_queue_paramGetMessageQueueParamGetMessageQueueParamGetMessageQueueParam, create_messagecreate_messageCreateMessageCreateMessageCreateMessage, clear_messageclear_messageClearMessageClearMessageClearMessage, set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleSetMessageTuple, get_message_tupleget_message_tupleGetMessageTupleGetMessageTupleGetMessageTuple, set_message_objset_message_objSetMessageObjSetMessageObjSetMessageObj, get_message_objget_message_objGetMessageObjGetMessageObjGetMessageObj

Module

Foundation