dequeue_messageT_dequeue_messageDequeueMessageDequeueMessagedequeue_message出队列消息（算子）

名称

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

签名

描述

dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message 从由 QueueHandleQueueHandleQueueHandleQueueHandlequeueHandlequeue_handle 参数指定的消息队列中取出一个消息。该消息必须是由任何线程使用 enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessageenqueue_message 放入队列的。

消息按 FIFO（先入先出）顺序交付，每条消息仅交付一次。如果队列不为空，dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message 会立即从队列中取出最旧的消息。该消息将从队列中移除，并通过 MessageHandleMessageHandleMessageHandleMessageHandlemessageHandlemessage_handle 输出参数返回该消息的句柄。消息数据的所有权将从消息队列转移（不进行复制）至新创建的消息句柄。

如果队列为空，dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message 会阻塞，直到有消息可供发送（即由另一个线程使用 enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessageenqueue_message 放入队列）。

可以通过 get_message_tupleget_message_tupleGetMessageTupleGetMessageTupleGetMessageTupleget_message_tuple、get_message_objget_message_objGetMessageObjGetMessageObjGetMessageObjget_message_obj 或 get_message_paramget_message_paramGetMessageParamGetMessageParamGetMessageParamget_message_param 查询消息中存储的数据。。

通过 dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message 获得的消息句柄可以进一步复用（进行修改和/或放入另一个消息队列）。

如果通过单次 enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessageenqueue_message 调用将多条消息入队，那么所有这些消息也将通过单次 dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message 调用一起取出，并通过 MessageHandleMessageHandleMessageHandleMessageHandlemessageHandlemessage_handle 元组返回多个消息句柄。

队列访问在内部是完全同步的，无需外部锁定。

在应用程序重新配置或清理过程中，可能需要唤醒在 dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message 中等待消息的线程。这可以通过 set_message_queue_paramset_message_queue_paramSetMessageQueueParamSetMessageQueueParamSetMessageQueueParamset_message_queue_param 算子配合 'abort_dequeuing'"abort_dequeuing""abort_dequeuing""abort_dequeuing""abort_dequeuing""abort_dequeuing" 参数来实现。在这种情况下，当前被阻塞的 dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message 调用将立即返回 H_ERR_MQCNCL 错误。

最后，可以通过 GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name 和 GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value 中的泛型参数来调整 dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message 的行为。目前仅支持一个泛型参数：

'timeout'"timeout""timeout""timeout""timeout""timeout"：

超时时间控制算子在队列为空时等待消息的阻塞时长。超时后，算子将返回 H_ERR_TIMEOUT 错误代码。超时时间可以指定为以秒为单位的整数或双精度数值，也可以指定为字符串 'infinite'"infinite""infinite""infinite""infinite""infinite"。若未指定超时时间，则默认使用无限超时，这意味着算子将一直阻塞，直到有新消息入队或操作被中止。

执行信息

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

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

参数

示例（HDevelop）

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

结果

如果操作成功，dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message 返回 2 (H_MSG_TRUE)。否则将抛出异常。可能的错误情况包括参数无效、消息出队等待超时（H_ERR_TIMEOUT）或消息出队等待中止（H_ERR_MQCNCL）。请注意，在极少数情况下，如果算子调用结束时发生错误（此时消息已从队列中移除），算子会尝试将消息放回队列头部以避免丢失。如果在此期间另一个线程从队列中移除了另一条消息，这可能会导致消息传递顺序发生变化。

可能的后继

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

模块

基础