dequeue_message — Empfangen einer oder mehrerer Nachrichten aus einer Warteschlange.
dequeue_message( : : QueueHandle, GenParamName, GenParamValue : MessageHandle)
dequeue_message empfängt eine Nachricht aus einer
Warteschlange die in QueueHandle referenziert ist. Die
Nachricht muss zuvor von einem beliebigen Thread mit Hilfe des
Operators enqueue_message in die Warteschlange eingereiht
worden sein.
Die Nachrichten werden in FIFO (first-in first-out) Reihenfolge
empfangen, wobei die Nachrichten unabhängig von der Anzahl der
wartenden Threads jeweils nur einmal empfangen werden können. Falls die
Warteschlange Nachrichten enthält, entnimmt dequeue_message
sofort die älteste Nachricht und gibt eine Referenz auf das
Nachrichtenobjekt im Parameter MessageHandle zurück. Der
Besitz auf die Nachrichtendaten geht damit von der Warteschlange auf
die zurückgegebene Nachrichtenreferenz über.
Falls die Warteschlange leer ist, wartet dequeue_message bis
ein Nachrichtenobjekt für die Entnahme aus der
Warteschlange verfügbar ist (nachdem sie zuvor von einem anderen Thread
in die Warteschlange mit Hilfe von enqueue_message eingereiht
wurde).
Die Daten, die ein Nachrichtenobjekt enthält können anschließend
über die Operatoren get_message_param,
get_message_tuple oder get_message_obj abgefragt
werden.
Die Nachrichtenobjekte, die man von dequeue_message erhält,
können anschließend wiederverwendet, d.h. modifiziert und/oder in
eine weitere Warteschlange eingereiht werden.
Falls mehrere Nachrichtenobjekte über einen einzelnen Aufruf von
enqueue_message in die Warteschlange eingereiht wurden,
werden all diese Nachrichtenobjekte auch wieder zusammen durch einen
einzelnen Aufruf von dequeue_message der Warteschlange
entnommen und als Tupel im Parameter MessageHandle
zurückgegeben.
Der Zugriff auf die Warteschlange ist intern synchronisiert. Es müssen daher keine weiteren Synchronisationsmaßnahmen getroffen werden.
Es kann z.B. während einer Rekonfigurierung oder dem Aufräumen für
eine Applikation notwendig werden, Threads die im Operator
dequeue_message auf Nachrichten warten aufzuwecken und die
Operation abzubrechen. Dies erreicht man indem man den Operator
set_message_queue_param mit dem Parameter
'abort_dequeuing' verwendet. In diesem Fall wird der
blockierte Operator dequeue_message sofort mit dem Fehler
H_ERR_MQCNCL zurückkehren.
Es ist möglich das Verhalten von dequeue_message durch die
generischen Parameter GenParamName und
GenParamValue zu beeinflussen. Aktuell wird nur ein
einziger Parameter unterstützt:
Spezifiziert eine Spanne für eine Zeitüberschreitung, welche bestimmt, wie lange der Operator auf eine Nachricht maximal warten soll, wenn die Warteschlange leer sein sollte. Wenn die Zeitspanne überschritten wurde, 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 ein Nachrichtenobjekt aus der Warteschlange entnehmen kann oder die Operation von außen abgebrochen wird.
Dieser Operator liefert ein Handle zurück. Es ist zu beachten, dass der Zustand einer Instanz dieses Handletyps durch bestimmte Operatoren geändert werden kann, obwohl das Handle als Eingabeparameter in diesen Operatoren verwendet wird.
QueueHandle (input_control) message_queue → (handle)
Warteschlangenobjekt.
Parameteranzahl: QueueHandle == 1
Restriktion: QueueHandle != 0
GenParamName (input_control) string(-array) → (string)
Name der generischen Parameter
Parameteranzahl: GenParamName == GenParamValue
Defaultwert: 'timeout'
Werteliste: 'timeout'
GenParamValue (input_control) tuple(-array) → (string / integer / real)
Werte der generischen Parameter
Parameteranzahl: GenParamName == GenParamValue
Defaultwert: 'infinite'
Werteliste: 'infinite'
MessageHandle (output_control) message(-array) → (handle)
Entnommene Nachrichtenobjekte.
Parameteranzahl: MessageHandle > 0
Zusicherung: MessageHandle != 0
create_message_queue (Queue) * ... dequeue_message (Queue, [], [], Message) get_message_obj (Image, Message, 'my_image')
Im Erfolgsfall gibt dequeue_message den Wert 2 (H_MSG_TRUE) zurück.
Andernfalls wird eine Fehlerbehandlung durchgeführt. Mögliche Fehler
können durch ungültige Parameter, Zeitüberschreitung (H_ERR_TIMEOUT)
oder externes Abbrechen (H_ERR_MQCNCL) verursacht werden. Sollte in
seltenen Fällen intern ein Fehler auftreten nachdem die Nachricht
bereits aus der Queue genommen wurde, wird der Operator die Nachricht
wieder an den Anfang der Warteschlange einreihen. Dies kann zu einer
veränderten Reihenfolge der entnommenen Nachrichten führen, Wenn
zwischenzeitlich ein anderer Thread eine Nachricht aus der
Warteschlange entnommen hat.
get_message_tuple,
get_message_obj,
get_message_param
create_message_queue,
clear_message_queue,
enqueue_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