create_messagecreate_messageCreateMessagecreate_messageCreateMessageCreateMessage (Operator)

Name

create_messagecreate_messageCreateMessagecreate_messageCreateMessageCreateMessage — Create a new empty message.

create_messagecreate_messageCreateMessagecreate_messageCreateMessageCreateMessage creates a new empty message. The output parameter MessageHandleMessageHandleMessageHandleMessageHandleMessageHandlemessageHandle is a handle to the newly created message and is used to identify the message in any subsequent operator call using the message.

The message serves as a dictionary-like container allowing to store an arbitrary number of values associated with unique keys (strings). Each key can refer either to a control parameter tuple or to an iconic object. These data are stored to the message using set_message_tupleset_message_tupleSetMessageTupleset_message_tupleSetMessageTupleSetMessageTuple or set_message_objset_message_objSetMessageObjset_message_objSetMessageObjSetMessageObj, respectively, from where they can be retrieved again using get_message_tupleget_message_tupleGetMessageTupleget_message_tupleGetMessageTupleGetMessageTuple or get_message_objget_message_objGetMessageObjget_message_objGetMessageObjGetMessageObj.

The data stored in the message are always deep copies of the original data, being it control parameters or objects. The original data can thus be reused immediately after the set_message_tupleset_message_tupleSetMessageTupleset_message_tupleSetMessageTupleSetMessageTuple or set_message_objset_message_objSetMessageObjset_message_objSetMessageObjSetMessageObj calls without affecting the message. Notable exceptions are handles which are treated as regular integer values by HALCON, therefore storing any handle in the message will copy the handle value, but not the resource behind the handle.

Finally, the messages can be passed between the threads of an application using asynchronous message queues. The data can be appended to the queue by multiple producer threads using enqueue_messageenqueue_messageEnqueueMessageenqueue_messageEnqueueMessageEnqueueMessage and retrieved from the queue by multiple receiver threads using dequeue_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage. All these operations are internally properly synchronized. Therefore, the queue can be safely accessed by all producers and consumers without any explicit locking. All the enqueued messages 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.

When the message is no more needed, all associated resources, in particular the tuple or object data stored in the message, should be released using clear_messageclear_messageClearMessageclear_messageClearMessageClearMessage.

Parallelization

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

Parameters

MessageHandleMessageHandleMessageHandleMessageHandleMessageHandlemessageHandle (output_control) message → (integer)

Handle of the newly created message.

Number of elements: MessageHandle == 1

Assertion: MessageHandle != 0

Example (HDevelop)

MessageHandles := []
for idx := 0 to 4 by 1
  create_message (MessageHandle)
  MessageHandles[idx]:= MessageHandle
endfor
* ...
clear_message (MessageHandles)