ClassesClassesClassesClasses | | | | Operators

enqueue_messageT_enqueue_messageEnqueueMessageenqueue_messageEnqueueMessageEnqueueMessage (Operator)

Name

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

Signature

enqueue_message( : : QueueHandle, MessageHandle, GenParamName, GenParamValue : )

Herror T_enqueue_message(const Htuple QueueHandle, const Htuple MessageHandle, const Htuple GenParamName, const Htuple GenParamValue)

Herror enqueue_message(const HTuple& QueueHandle, const HTuple& MessageHandle, const HTuple& GenParamName, const HTuple& GenParamValue)

void HMessageQueue::EnqueueMessage(const HTuple& MessageHandle, const HTuple& GenParamName, const HTuple& GenParamValue) const

void EnqueueMessage(const HTuple& QueueHandle, const HTuple& MessageHandle, const HTuple& GenParamName, const HTuple& GenParamValue)

void HMessageQueue::EnqueueMessage(const HMessageArray& MessageHandle, const HTuple& GenParamName, const HTuple& GenParamValue) const

void HMessageQueue::EnqueueMessage(const HMessage& MessageHandle, const HTuple& GenParamName, const HTuple& GenParamValue) const

void HOperatorSetX.EnqueueMessage(
[in] VARIANT QueueHandle, [in] VARIANT MessageHandle, [in] VARIANT GenParamName, [in] VARIANT GenParamValue)

void HMessageQueueX.EnqueueMessage(
[in] IHMessageX* MessageHandle, [in] VARIANT GenParamName, [in] VARIANT GenParamValue)

static void HOperatorSet.EnqueueMessage(HTuple queueHandle, HTuple messageHandle, HTuple genParamName, HTuple genParamValue)

void HMessageQueue.EnqueueMessage(HMessage[] messageHandle, HTuple genParamName, HTuple genParamValue)

void HMessageQueue.EnqueueMessage(HMessage messageHandle, HTuple genParamName, HTuple genParamValue)

Description

enqueue_messageenqueue_messageEnqueueMessageenqueue_messageEnqueueMessageEnqueueMessage enqueues one or more messages to the message queue denoted by the QueueHandleQueueHandleQueueHandleQueueHandleQueueHandlequeueHandle parameter. The enqueued messages can be retrieved from the queue by any thread using dequeue_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage.

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

Operator parameters GenParamNameGenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValueGenParamValuegenParamValue 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_paramSetMessageQueueParamset_message_queue_paramSetMessageQueueParamSetMessageQueueParam, the call would fail with H_ERR_MQOVL.

Parallelization

Parameters

QueueHandleQueueHandleQueueHandleQueueHandleQueueHandlequeueHandle (input_control)  message_queue HMessageQueue, HTupleHTupleHMessageQueue, HTupleHMessageQueueX, VARIANTHtuple (integer) (IntPtr) (Hlong) (Hlong) (Hlong) (Hlong)

Message queue handle.

Number of elements: QueueHandle == 1

Restriction: QueueHandle != 0

MessageHandleMessageHandleMessageHandleMessageHandleMessageHandlemessageHandle (input_control)  message(-array) HMessage, HTupleHTupleHMessage, HTupleHMessageX, VARIANTHtuple (integer) (IntPtr) (Hlong) (Hlong) (Hlong) (Hlong)

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

Number of elements: MessageHandle > 0

Restriction: MessageHandle != 0

GenParamNameGenParamNameGenParamNameGenParamNameGenParamNamegenParamName (input_control)  string-array HTupleHTupleHTupleVARIANTHtuple (string) (string) (HString) (char*) (BSTR) (char*)

Names of optional generic parameters.

Number of elements: GenParamName == GenParamValue

GenParamValueGenParamValueGenParamValueGenParamValueGenParamValuegenParamValue (input_control)  tuple-array HTupleHTupleHTupleVARIANTHtuple (string / integer / real) (string / int / long / double) (HString / Hlong / double) (char* / Hlong / double) (BSTR / Hlong / double) (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, [], [])
clear_message (Message)

Result

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

Possible Predecessors

set_message_tupleset_message_tupleSetMessageTupleset_message_tupleSetMessageTupleSetMessageTuple, set_message_objset_message_objSetMessageObjset_message_objSetMessageObjSetMessageObj

See also

create_message_queuecreate_message_queueCreateMessageQueuecreate_message_queueCreateMessageQueueCreateMessageQueue, clear_message_queueclear_message_queueClearMessageQueueclear_message_queueClearMessageQueueClearMessageQueue, dequeue_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage, set_message_queue_paramset_message_queue_paramSetMessageQueueParamset_message_queue_paramSetMessageQueueParamSetMessageQueueParam, get_message_queue_paramget_message_queue_paramGetMessageQueueParamget_message_queue_paramGetMessageQueueParamGetMessageQueueParam, create_messagecreate_messageCreateMessagecreate_messageCreateMessageCreateMessage, clear_messageclear_messageClearMessageclear_messageClearMessageClearMessage, set_message_tupleset_message_tupleSetMessageTupleset_message_tupleSetMessageTupleSetMessageTuple, get_message_tupleget_message_tupleGetMessageTupleget_message_tupleGetMessageTupleGetMessageTuple, set_message_objset_message_objSetMessageObjset_message_objSetMessageObjSetMessageObj, get_message_objget_message_objGetMessageObjget_message_objGetMessageObjGetMessageObj

Module

Foundation


ClassesClassesClassesClasses | | | | Operators