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.
Falls die Warteschlange nach der Operation eine größere Anzahl von
Nachrichten halten würde als die spezifizierte Maximalanzahl, wird
entweder der Fehler H_ERR_MQOVL zurückgegeben oder gewartet bis Platz
in der Warteschlange frei wird.
Das Verhalten kann für die Warteschlange mittels
dem Parameter 'wait_on_full' im Operator
set_message_queue_param gesetzt werden.
Die Maximalanzahl von gehaltenen Nachrichten wird über den Parameterwert
'max_message_num' im Operator set_message_queue_param
festgelegt.
Falls mehr Nachrichten eingereiht werden sollen als die
spezifizierte Maximalanzahl, d.h. falls das Tupel
MessageHandle mehr Einträge hat als 'max_message_num',
so gibt enqueue_message immer den Fehler H_ERR_MQOVL zurück,
unabhängig von der Einstellung von 'wait_on_full'.
Es ist möglich das Verhalten von enqueue_message durch die
generischen Parameter GenParamName und
GenParamValue zu beeinflussen. Aktuell wird nur ein
einziger Parameter unterstützt:
Spezifiziert wie lange der Operator maximal warten soll, wenn die Warteschlange voll ist und 'wait_on_full' auf 'true' gesetzt ist. Im Falle einer Zeitüberschreitung kehrt der Operator mit dem Fehler H_ERR_TIMEOUT zurück.
Die Spanne für die Zeitüberschreitung kann als Integer- oder Doublewert in Sekunden angegeben werden oder durch den String 'infinite'. Wenn keine Zeitüberschreitung angegeben wurde wird implizit eine unendliche Zeitspanne (infinite) angenommen und der Operator blockiert bis er das oder die Nachrichtenobjekte in die Warteschlange einreihen kann oder die Operation von außen abgebrochen wird.
Wertevorschläge: -1, 'infinite', 1, 10
Default: -1
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