enqueue_message — Einreihen von Nachrichtenobjekten in eine Warteschlange.
enqueue_message( : : QueueHandle, MessageHandle, GenParamName, GenParamValue : )
enqueue_message reiht eine oder mehrere Nachrichtenobjekte
in eine Warteschlange ein, die durch den Parameter
QueueHandle referenziert wird. Die eingereihten Nachrichten
können wieder durch den Operator dequeue_message der Reihe
nach ausgelesen werden.
Die einzureihenden Nachrichtenobjekte (vgl. create_message)
werden im Parameter MessageHandle übergeben welcher sowohl
einzelne als auch Tupel von Nachrichtenobjekten akzeptiert. Wenn
mehrere Nachrichtenobjekte zusammen der Warteschlange angehängt
werden, werden diese auch wieder zusammen durch den Operator
dequeue_message ausgegeben.
Es können gleichzeitig sowohl mehrere Erzeuger (enqueuing) Threads zu einer Warteschlange Nachrichten schicken als auch mehrere Verbraucher (dequeuing) Threads aus der gleichen Warteschlange Nachrichten holen. Die Warteschlange ist als FIFO (first-in first-out) Puffer organisiert, wobei jede Nachricht unabhängig vom Thread nur einmal aus der Warteschlange ausgelesen werden kann.
Der Zugriff auf die Warteschlange ist intern synchronisiert, so dass
vom Benutzer keine zusätzlichen externen
Synchronisationsmaßnahmen notwendig sind. Wenn die Warteschlange
leer ist und mindestens ein Verbraucherthread auf eine Nachricht in
dequeue_message wartet, erhält einer der wartenden Threads
eine Nachricht und wird aufgeweckt, sobald ein Erzeugerthread mit
Hilfe von enqueue_message ebendiese Nachricht erfolgreich in
die Warteschlange gestellt hat. Andernfalls wird die Nachricht an
die Warteschlange asynchron angehängt, um an einen Verbraucherthread
weitergereicht zu werden, sobald dieser bereit ist die Nachricht zu
entnehmen.
enqueue_message kopiert die Nachricht in die Warteschlange,
weshalb das ursprüngliche Nachrichtenobjekt danach sofort weiterverwendet
werden kann, ohne das kopierte Nachrichtenobjekt zu beeinflussen.
Die Parameter GenParamName und GenParamValue
sind für zukünftige Erweiterungen des Operators reserviert. Es
werden aktuell keine generischen Parameterwerte unterstützt.
Falls die Warteschlange nach der Operation eine größere Anzahl von
Nachrichten halten würde als die spezifizierte Maximalanzahl, wird
der Fehler H_ERR_MQOVL zurückgegeben. Die Maximalanzahl von
gehaltenen Nachrichten wird über den Parameterwert
'max_message_num' im Operator set_message_queue_param
festgelegt.
QueueHandle (input_control) message_queue → (handle)
Warteschlangenobjekt.
Parameteranzahl: QueueHandle == 1
Restriktion: QueueHandle != 0
MessageHandle (input_control) message(-array) → (handle)
Einzureihende Nachrichtenobjekte.
Parameteranzahl: MessageHandle > 0
Restriktion: MessageHandle != 0
GenParamName (input_control) string-array → (string)
Namen generischer Parameter.
Parameteranzahl: GenParamName == GenParamValue
GenParamValue (input_control) tuple-array → (string / integer / real)
Werte generischer Parameter.
Parameteranzahl: GenParamName == GenParamValue
create_message_queue (Queue) * ... create_message (Message) set_message_tuple (Message, 'mixed_tuple', ['The answer', 42]) enqueue_message (Queue, Message, [], [])
Im Erfolgsfall gibt enqueue_message den Wert 2 (H_MSG_TRUE) zurück.
Andernfalls wird eine Fehlerbehandlung durchgeführt. Mögliche Fehler
können ungültige Parameter oder Allokierungsfehler sein.
set_message_tuple,
set_message_obj
create_message_queue,
clear_message_queue,
dequeue_message,
set_message_queue_param,
get_message_queue_param,
create_message,
clear_message,
set_message_tuple,
get_message_tuple,
set_message_obj,
get_message_obj
Foundation