dequeue_messageT_dequeue_messageDequeueMessageDequeueMessagedequeue_message (算子)

名称

dequeue_messageT_dequeue_messageDequeueMessageDequeueMessagedequeue_message — 从消息队列接收一条或多条消息。

签名

描述

dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message dequeues a message from the message queue denoted by the QueueHandleQueueHandleQueueHandleQueueHandlequeueHandlequeue_handle parameter. The message must have been enqueued by any thread using enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessageenqueue_message。

The messages are delivered in FIFO (first-in first-out) order, every message is delivered only once. If the queue is not empty, dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message 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 MessageHandleMessageHandleMessageHandleMessageHandlemessageHandlemessage_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_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message blocks until a message becomes available for delivery (being queued from another thread using enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessageenqueue_message).

The data stored in the message can be queried using get_message_tupleget_message_tupleGetMessageTupleGetMessageTupleGetMessageTupleget_message_tuple, get_message_objget_message_objGetMessageObjGetMessageObjGetMessageObjget_message_obj, or get_message_paramget_message_paramGetMessageParamGetMessageParamGetMessageParamget_message_param。

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

If multiple messages were enqueued using a single enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessageenqueue_message call, all those messages will be also retrieved together through a single dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message call, delivering multiple message handles via the MessageHandleMessageHandleMessageHandleMessageHandlemessageHandlemessage_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_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message. This can be achieved using the operator set_message_queue_paramset_message_queue_paramSetMessageQueueParamSetMessageQueueParamSetMessageQueueParamset_message_queue_param with the parameter 'abort_dequeuing'"abort_dequeuing""abort_dequeuing""abort_dequeuing""abort_dequeuing""abort_dequeuing". In such case the currently blocked dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message calls return immediately with H_ERR_MQCNCL.

Finally, it is possible to adjust dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message behavior through generic parameters within GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value. Currently, just a single generic parameter is supported:

'timeout'"timeout""timeout""timeout""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""infinite""infinite""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.

执行信息

• 多线程类型：独立（即使使用独占算子也能并行运行）。
• 多线程作用域：全局（可从任何线程调用）。
• 未采用并行化处理。

此算子返回一个句柄。请注意，即使该句柄被用作特定算子的输入参数，这些算子仍可能改变此句柄类型的实例状态。

参数

示例（HDevelop）

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

结果

If the operation succeeds, dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message 返回 2 ( H_MSG_TRUE )。否则将抛出异常。 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.

可能的后继

get_message_tupleget_message_tupleGetMessageTupleGetMessageTupleGetMessageTupleget_message_tuple, get_message_objget_message_objGetMessageObjGetMessageObjGetMessageObjget_message_obj, get_message_paramget_message_paramGetMessageParamGetMessageParamGetMessageParamget_message_param

另见

create_message_queuecreate_message_queueCreateMessageQueueCreateMessageQueueCreateMessageQueuecreate_message_queue, clear_message_queueclear_message_queueClearMessageQueueClearMessageQueueClearMessageQueueclear_message_queue, enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessageenqueue_message, set_message_queue_paramset_message_queue_paramSetMessageQueueParamSetMessageQueueParamSetMessageQueueParamset_message_queue_param, get_message_queue_paramget_message_queue_paramGetMessageQueueParamGetMessageQueueParamGetMessageQueueParamget_message_queue_param, create_messagecreate_messageCreateMessageCreateMessageCreateMessagecreate_message, clear_messageclear_messageClearMessageClearMessageClearMessageclear_message, set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleSetMessageTupleset_message_tuple, get_message_tupleget_message_tupleGetMessageTupleGetMessageTupleGetMessageTupleget_message_tuple, set_message_objset_message_objSetMessageObjSetMessageObjSetMessageObjset_message_obj, get_message_objget_message_objGetMessageObjGetMessageObjGetMessageObjget_message_obj

模块

基础