create_messageCreateMessageCreateMessagecreate_messageT_create_message🔗

Short description🔗

create_messageCreateMessageCreateMessagecreate_messageT_create_message — Create a new empty message.

Signature🔗

create_message( out message MessageHandle )def create_message( ) -> HHandle

void HMessage::HMessage( )

public HMessage( )

void HMessage::CreateMessage( )

void HMessage.CreateMessage( )

Description🔗

create_messageCreateMessage creates a new empty message. The output parameter MessageHandlemessageHandlemessage_handle 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 that can be passed between the threads of an application using asynchronous message queues. Alternatively, HALCON also provides dictionaries (create_dictCreateDict) to group parameters in programs and procedures.

Messages can store an arbitrary number of entries, each having its unique key (string or integer) and associated value. 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_tupleSetMessageTuple or set_message_objSetMessageObj, respectively, from where they can be retrieved again using get_message_tupleGetMessageTuple or get_message_objGetMessageObj.

The control parameter tuples stored in the message are always deep copies of the original data. The original data can thus be reused immediately after the set_message_tupleSetMessageTuple call without affecting the message. Notable exceptions are handles: Storing any handle in the message will copy the handle value, but not the resource behind the handle.

As mentioned above, 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_messageEnqueueMessage and retrieved from the queue by multiple receiver threads using dequeue_messageDequeueMessage. 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_messageEnqueueMessage operation. The original message(s) can thus be immediately reused after the enqueue_messageEnqueueMessage call without affecting the enqueued copy.

Execution information🔗

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🔗

MessageHandlemessageHandlemessage_handle (output_control) message → (handle)HTuple (HHandle)HMessage, HTuple (IntPtr)HHandleHtuple (handle)

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
* ...

Result🔗

Returns 2 (H_MSG_TRUE) unless a resource allocation error occurs.

Combinations with other operators🔗

Combinations

Possible successors

set_message_tupleSetMessageTuple, set_message_objSetMessageObj

Alternatives

create_dictCreateDict

Module🔗

Foundation