enqueue_messageEnqueueMessageEnqueueMessageenqueue_messageT_enqueue_message🔗

Short description🔗

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

Signature🔗

enqueue_message( message_queue QueueHandle, message MessageHandle, string GenParamName, tuple GenParamValue )

Description🔗

enqueue_messageEnqueueMessage enqueues one or more messages to the message queue denoted by the QueueHandlequeueHandlequeue_handle parameter. The enqueued messages can be retrieved from the queue by any thread using dequeue_messageDequeueMessage.

The messages (see create_messageCreateMessage) to be enqueued are specified in the MessageHandlemessageHandlemessage_handle parameter which accepts a single handle as well as tuple of handles. When enqueuing multiple handles together in a single enqueue_messageEnqueueMessage call, they are delivered again together through a single dequeue_messageDequeueMessage 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_messageDequeueMessage, one of those threads is woken up by a successful enqueue_messageEnqueueMessage call and the enqueued message data are immediately delivered. Otherwise the message data is appended 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 (MessageHandlemessageHandlemessage_handle) are copied by the enqueue_messageEnqueueMessage operation. The original message(s) can thus be immediately reused after the enqueue_messageEnqueueMessage call without affecting the enqueued copy.

If, after the operation, the queue would hold a larger number of messages than the specified maximum number, either the error H_ERR_MQOVL is returned, or the operator waits until space becomes available in the queue. The behavior can be configured for the queue using the parameter 'wait_on_full'"wait_on_full" in the operator set_message_queue_paramSetMessageQueueParam. The maximum number of messages that may be held is defined by the parameter value 'max_message_num'"max_message_num" in the operator set_message_queue_paramSetMessageQueueParam. If more messages shall be enqueued than the queue has capacity, i.e. if the tuple MessageHandlemessageHandlemessage_handle has more elements than what is set in ValRe{‘max_message_num’}, the operator enqueue_messageEnqueueMessage will always return the error code H_ERR_MQOVL, independent of the setting of 'wait_on_full'"wait_on_full".

Finally, it is possible to adjust enqueue_messageEnqueueMessage behavior through generic parameters within GenParamNamegenParamNamegen_param_name and GenParamValuegenParamValuegen_param_value. Currently, just a single generic parameter is supported:

'timeout'"timeout": Timeout controlling how long the operator will block while waiting for space in the message queue to become available if the queue is full and 'wait_on_full'"wait_on_full" is set to 'true'"true". In case of a timeout, the operator returns with H_ERR_TIMEOUT.

The timeout can be specified as an integer or double value in seconds or as the string 'infinite'"infinite". When no timeout is specified, infinite timeout is used as default, meaning that the operator would block until space becomes available or until the operation is aborted.

Suggested values: -1-1, 'infinite'"infinite", 11, 1010

Default: -1-1

Execution information🔗

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🔗

QueueHandlequeueHandlequeue_handle (input_control) message_queue → (handle)HTuple (HHandle)HMessageQueue, HTuple (IntPtr)HHandleHtuple (handle)

Message queue handle.

Number of elements: QueueHandle == 1
Restriction: QueueHandle != 0

MessageHandlemessageHandlemessage_handle (input_control) message(-array) → (handle)HTuple (HHandle)HMessage, HTuple (IntPtr)MaybeSequence[HHandle]Htuple (handle)

Handle(s) of message(s) to be enqueued.

Number of elements: MessageHandle > 0
Restriction: MessageHandle != 0

GenParamNamegenParamNamegen_param_name (input_control) string-array → (string)HTuple (HString)HTuple (string)Sequence[str]Htuple (char*)

Names of optional generic parameters.

Number of elements: GenParamName == GenParamValue

GenParamValuegenParamValuegen_param_value (input_control) tuple-array → (string / integer / real)HTuple (HString / Hlong / double)HTuple (string / int / long / double)Sequence[Union[int, float, str]]Htuple (char* / Hlong / double)

Values of optional generic parameters.

Number of elements: GenParamName == GenParamValue

Example🔗

(HDevelop)

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

Result🔗

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

Combinations with other operators🔗

Combinations

Possible predecessors

set_message_tupleSetMessageTuple, set_message_objSetMessageObj

Module🔗

Foundation