create_messagecreate_messageCreateMessagecreate_messageCreateMessageCreateMessage (Operator)

Name

create_messagecreate_messageCreateMessagecreate_messageCreateMessageCreateMessage — Erzeugen einer neuen Nachricht.

create_messagecreate_messageCreateMessagecreate_messageCreateMessageCreateMessage erzeugt eine neue leere Nachricht. Der Ausgabeparameter MessageHandleMessageHandleMessageHandleMessageHandleMessageHandlemessageHandle referenziert das erzeugte Nachrichtenobjekt und wird dazu verwendet, um die Nachricht in den nachfolgenden Operatoraufrufen identifizieren zu können.

Eine Nachricht ist ein Objekt, das ähnlich einem assoziativem Array (Wörterbuch) aufgebaut ist. Es erlaubt eine beliebige Anzahl von Daten zu speichern, welche mit Hilfe eines eindeutigen Schlüsselwortes (String) identifiziert werden. Jedes Schlüsselwort kann entweder einen Tupeldaten-Parameter oder ein ikonisches Objekt referenzieren. Diese Daten werden in der Nachricht mit Hilfe der Operatoren set_message_objset_message_objSetMessageObjset_message_objSetMessageObjSetMessageObj und set_message_tupleset_message_tupleSetMessageTupleset_message_tupleSetMessageTupleSetMessageTuple gespeichert und können über die Operatoren get_message_objget_message_objGetMessageObjget_message_objGetMessageObjGetMessageObj und get_message_tupleget_message_tupleGetMessageTupleget_message_tupleGetMessageTupleGetMessageTuple wieder ausgelesen werden.

Die Daten, welche in den Nachrichten referenziert werden, sind stets Kopien ihrer Originale. Damit können die originalen Daten, nachdem sie in der Nachricht durch die Operatoren set_message_tupleset_message_tupleSetMessageTupleset_message_tupleSetMessageTupleSetMessageTuple oder set_message_objset_message_objSetMessageObjset_message_objSetMessageObjSetMessageObj gespeichert wurden, verändert oder gelöscht werden, ohne die Nachricht selbst zu verändern. Eine Ausnahme bilden Handles, welche von HALCON als üblicher Integerwert behandelt werden. Beim Speichern eines Handles in einer Nachricht wird daher nur der Handle-Wert, nicht aber das Handle-Objekt selbst kopiert.

Die erzeugten Nachrichten können zwischen Threads einfach über eine Warteschlange für Nachrichten ausgetauscht werden. Mit Hilfe des Operators enqueue_messageenqueue_messageEnqueueMessageenqueue_messageEnqueueMessageEnqueueMessage können Nachrichten aus mehreren Erzeuger-Threads an eine Warteschlange angehängt und über den Operator dequeue_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage aus mehreren Verbraucher-Threads wieder aus der Warteschlange entnommen werden. All diese Operationen werden intern synchronisiert, so dass der Mechanismus über die Warteschlange ohne externe Synchronisation auskommt. enqueue_messageenqueue_messageEnqueueMessageenqueue_messageEnqueueMessageEnqueueMessage kopiert die Nachricht in die Warteschlange, weshalb das ursprüngliche Nachrichtenobjekt danach sofort weiterverwendet werden kann, ohne das kopierte Nachrichtenobjekt zu beeinflussen.

Wenn die Nachricht nicht mehr verwendet wird, können alle mit der Nachricht verbundenen Ressourcen, insbesondere die gespeicherten Tupeldaten und ikonischen Objekte, mit Hilfe des Operators clear_messageclear_messageClearMessageclear_messageClearMessageClearMessage freigegeben werden.

Parallelisierung

Multithreading-Typ: reentrant (läuft parallel zu nicht-exklusiven Operatoren).
Multithreading-Bereich: global (kann von jedem Thread aufgerufen werden).
Wird ohne Parallelisierung verarbeitet.

Parameter

MessageHandleMessageHandleMessageHandleMessageHandleMessageHandlemessageHandle (output_control) message → (integer)

Nachrichtenobjekt.

Parameteranzahl: MessageHandle == 1

Zusicherung: MessageHandle != 0

Beispiel (HDevelop)

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

Ergebnis

create_messagecreate_messageCreateMessagecreate_messageCreateMessageCreateMessage liefert den Wert 2 (H_MSG_TRUE), sofern kein Allokierungsfehler auftritt.