dequeue_messageDequeueMessageDequeueMessagedequeue_messageT_dequeue_message🔗

Short description🔗

dequeue_messageDequeueMessageDequeueMessagedequeue_messageT_dequeue_message — Receive one or more messages from the message queue.

Signature🔗

dequeue_message( message_queue QueueHandle, string GenParamName, tuple GenParamValue, out message MessageHandle )

Description🔗

dequeue_messageDequeueMessage dequeues a message from the message queue denoted by the QueueHandlequeueHandlequeue_handle parameter. The message must have been enqueued by any thread using enqueue_messageEnqueueMessage.

The messages are delivered in FIFO (first-in first-out) order, every message is delivered only once. If the queue is not empty, dequeue_messageDequeueMessage immediately delivers the oldest message from the queue. This message is removed from the queue and a handle to the message is returned in the MessageHandlemessageHandlemessage_handle output parameter. The message data ownership is transferred (no copy) from the message queue to the newly created message handle.

If the queue is empty, dequeue_messageDequeueMessage blocks until a message becomes available for delivery (being queued from another thread using enqueue_messageEnqueueMessage).

The data stored in the message can be queried using get_message_tupleGetMessageTuple, get_message_objGetMessageObj, or get_message_paramGetMessageParam.

The message handles obtained through dequeue_messageDequeueMessage can be further reused (modified and/or enqueued to another message queue).

If multiple messages were enqueued using a single enqueue_messageEnqueueMessage call, all those messages will be also retrieved together through a single dequeue_messageDequeueMessage call, delivering multiple message handles via the MessageHandlemessageHandlemessage_handle tuple.

The queue access is internally fully synchronized, no external locking is required.

During application reconfiguration or cleanup, it might be necessary to wake threads waiting for messages in dequeue_messageDequeueMessage. This can be achieved using the operator set_message_queue_paramSetMessageQueueParam with the parameter 'abort_dequeuing'"abort_dequeuing". In such case the currently blocked dequeue_messageDequeueMessage calls return immediately with H_ERR_MQCNCL.

Finally, it is possible to adjust dequeue_messageDequeueMessage 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 a message if the queue is empty. When expired, 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 a new message is enqueued 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.

This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.

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

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

Names of optional generic parameters

Number of elements: GenParamName == GenParamValue
Default: 'timeout'"timeout"
List of values: 'timeout'"timeout"

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

Values of optional generic parameters

Number of elements: GenParamName == GenParamValue
Default: 'infinite'"infinite"
List of values: 'infinite'"infinite"

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

Handle(s) of the dequeued message(s).

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

Example🔗

(HDevelop)

create_message_queue (Queue)
* ...
dequeue_message (Queue, [], [], Message)
get_message_obj (Image, Message, 'my_image')

Result🔗

If the operation succeeds, dequeue_messageDequeueMessage returns 2 (H_MSG_TRUE). Otherwise an exception is raised. Possible error conditions include invalid parameters, message dequeue wait timeout (H_ERR_TIMEOUT) or message dequeue wait abortion (H_ERR_MQCNCL). Note that in some rare cases, when an error occurs when finishing the operator call (after the message has already been removed from the queue), the operator will attempt to put the message back at the head of the queue to not lose it. This might lead to a different message delivery order if another thread removed another message from the queue in the meanwhile.

Combinations with other operators🔗

Combinations

Possible successors

get_message_tupleGetMessageTuple, get_message_objGetMessageObj, get_message_paramGetMessageParam

Module🔗

Foundation