enqueue_messageT_enqueue_messageEnqueueMessageEnqueueMessageenqueue_message (算子)

名称

enqueue_messageT_enqueue_messageEnqueueMessageEnqueueMessageenqueue_message — 将一条或多条消息排入消息队列。

签名

描述

enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessageenqueue_message enqueues one or more messages to the message queue denoted by the QueueHandleQueueHandleQueueHandleQueueHandlequeueHandlequeue_handle parameter. The enqueued messages can be retrieved from the queue by any thread using dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_message。

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

Operator parameters GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value 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""max_message_num" of operator set_message_queue_paramset_message_queue_paramSetMessageQueueParamSetMessageQueueParamSetMessageQueueParamset_message_queue_param, the call would fail with H_ERR_MQOVL.

执行信息

• 多线程类型：可重入（与非独占算子并行运行）。
• 多线程作用域：全局（可从任何线程调用）。
• 未采用并行化处理。

参数

示例（HDevelop）

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

结果

If the operation succeeds, enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessageenqueue_message 返回 2 ( H_MSG_TRUE )。否则将抛出异常。 Possible error conditions include invalid parameters or resource allocation error.

可能的前趋

set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleSetMessageTupleset_message_tuple, set_message_objset_message_objSetMessageObjSetMessageObjSetMessageObjset_message_obj

另见

create_message_queuecreate_message_queueCreateMessageQueueCreateMessageQueueCreateMessageQueuecreate_message_queue, clear_message_queueclear_message_queueClearMessageQueueClearMessageQueueClearMessageQueueclear_message_queue, dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessagedequeue_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

模块

基础