Operator Reference

HALCON Operator Reference / System / Multithreading

• HDevelop
• .NET
• Python
• C++
• C

ClassesClasses | | Operators

enqueue_messageT_enqueue_messageEnqueueMessageEnqueueMessageenqueue_message (Operator)

enqueue_messageT_enqueue_messageEnqueueMessageEnqueueMessageenqueue_message — 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)

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

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)

def enqueue_message(queue_handle: HHandle, message_handle: MaybeSequence[HHandle], gen_param_name: Sequence[str], gen_param_value: Sequence[Union[int, float, str]]) -> None

Description

enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageenqueue_message enqueues one or more messages to the message queue denoted by the QueueHandleQueueHandleQueueHandlequeueHandlequeue_handle parameter. The enqueued messages can be retrieved from the queue by any thread using dequeue_messagedequeue_messageDequeueMessageDequeueMessagedequeue_message.

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

Operator parameters GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name and GenParamValueGenParamValueGenParamValuegenParamValuegen_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" of operator set_message_queue_paramset_message_queue_paramSetMessageQueueParamSetMessageQueueParamset_message_queue_param, the call would fail with H_ERR_MQOVL.

Execution Information

• Multithreading type: reentrant (runs in parallel with non-exclusive operators).
• Multithreading scope: global (may be called from any thread).
• Processed without parallelization.

Parameters

QueueHandleQueueHandleQueueHandlequeueHandlequeue_handle (input_control)  message_queue → HMessageQueue, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Message queue handle.

Number of elements: QueueHandle == 1

Restriction: QueueHandle != 0

MessageHandleMessageHandleMessageHandlemessageHandlemessage_handle (input_control)  message(-array) → HMessage, HTupleMaybeSequence[HHandle]HTupleHtuple (handle) (IntPtr) (HHandle) (handle)

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

Number of elements: MessageHandle > 0

Restriction: MessageHandle != 0

GenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (input_control)  string-array → HTupleSequence[str]HTupleHtuple (string) (string) (HString) (char*)

Names of optional generic parameters.

Number of elements: GenParamName == GenParamValue

GenParamValueGenParamValueGenParamValuegenParamValuegen_param_value (input_control)  tuple-array → HTupleSequence[Union[int, float, str]]HTupleHtuple (string / integer / real) (string / int / long / double) (HString / 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, [], [])

Result

If the operation succeeds, enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageenqueue_message 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_tupleSetMessageTupleSetMessageTupleset_message_tuple, set_message_objset_message_objSetMessageObjSetMessageObjset_message_obj

See also

create_message_queuecreate_message_queueCreateMessageQueueCreateMessageQueuecreate_message_queue, clear_message_queueclear_message_queueClearMessageQueueClearMessageQueueclear_message_queue, dequeue_messagedequeue_messageDequeueMessageDequeueMessagedequeue_message, set_message_queue_paramset_message_queue_paramSetMessageQueueParamSetMessageQueueParamset_message_queue_param, get_message_queue_paramget_message_queue_paramGetMessageQueueParamGetMessageQueueParamget_message_queue_param, create_messagecreate_messageCreateMessageCreateMessagecreate_message, clear_messageclear_messageClearMessageClearMessageclear_message, set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleset_message_tuple, get_message_tupleget_message_tupleGetMessageTupleGetMessageTupleget_message_tuple, set_message_objset_message_objSetMessageObjSetMessageObjset_message_obj, get_message_objget_message_objGetMessageObjGetMessageObjget_message_obj

Module

Foundation

---

ClassesClasses | | Operators