dequeue_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage (Operator)

Name

dequeue_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage — Empfangen einer oder mehrerer Nachrichten aus einer Warteschlange.

Signatur

Beschreibung

dequeue_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage empfängt eine Nachricht aus einer Warteschlange die in QueueHandleQueueHandleQueueHandleQueueHandleQueueHandlequeueHandle referenziert ist. Die Nachricht muss zuvor von einem beliebigen Thread mit Hilfe des Operators enqueue_messageenqueue_messageEnqueueMessageenqueue_messageEnqueueMessageEnqueueMessage 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_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage sofort die älteste Nachricht und gibt eine Referenz auf das Nachrichtenobjekt im Parameter MessageHandleMessageHandleMessageHandleMessageHandleMessageHandlemessageHandle 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_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage 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_messageenqueue_messageEnqueueMessageenqueue_messageEnqueueMessageEnqueueMessage eingereiht wurde).

Die Daten, die ein Nachrichtenobjekt enthält können anschließend über die Operatoren get_message_paramget_message_paramGetMessageParamget_message_paramGetMessageParamGetMessageParam, get_message_tupleget_message_tupleGetMessageTupleget_message_tupleGetMessageTupleGetMessageTuple oder get_message_objget_message_objGetMessageObjget_message_objGetMessageObjGetMessageObj abgefragt werden.

Die Nachrichtenobjekte, die man von dequeue_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage erhält, können anschließend wiederverwendet, d.h. modifiziert und/oder in eine weitere Warteschlange eingereiht werden. Wenn das Nachrichtenobjekt nicht mehr benötigt wird, sollten alle Ressourcen der Nachricht, insbesondere der gespeicherten Tupel- und Objektdaten, mit Hilfe des Operators clear_messageclear_messageClearMessageclear_messageClearMessageClearMessage freigegeben werden.

Falls mehrere Nachrichtenobjekte über einen einzelnen Aufruf von enqueue_messageenqueue_messageEnqueueMessageenqueue_messageEnqueueMessageEnqueueMessage in die Warteschlange eingereiht wurden, werden all diese Nachrichtenobjekte auch wieder zusammen durch einen einzelnen Aufruf von dequeue_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage der Warteschlange entnommen und als Tupel im Parameter MessageHandleMessageHandleMessageHandleMessageHandleMessageHandlemessageHandle 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_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage auf Nachrichten warten aufzuwecken und die Operation abzubrechen. Dies erreicht man indem man den Operator set_message_queue_paramset_message_queue_paramSetMessageQueueParamset_message_queue_paramSetMessageQueueParamSetMessageQueueParam mit dem Parameter 'abort_dequeuing'"abort_dequeuing""abort_dequeuing""abort_dequeuing""abort_dequeuing""abort_dequeuing" verwendet. In diesem Fall wird der blockierte Operator dequeue_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage sofort mit dem Fehler H_ERR_MQCNCL zurückkehren.

Es ist möglich das Verhalten von dequeue_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage durch die generischen Parameter GenParamNameGenParamNameGenParamNameGenParamNameGenParamNamegenParamName und GenParamValueGenParamValueGenParamValueGenParamValueGenParamValuegenParamValue zu beeinflussen. Aktuell wird nur ein einziger Parameter unterstützt:

'timeout'"timeout""timeout""timeout""timeout""timeout":

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'"infinite""infinite""infinite""infinite""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.

Parallelisierung

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

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.

Parameter

Beispiel (HDevelop)

	create_message_queue (Queue)
* ...
dequeue_message (Queue, [], [], Message)
get_message_obj (Image, Message, 'my_image')
clear_message (Message)

Ergebnis

Im Erfolgsfall gibt dequeue_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage 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.

Nachfolger

get_message_tupleget_message_tupleGetMessageTupleget_message_tupleGetMessageTupleGetMessageTuple, get_message_objget_message_objGetMessageObjget_message_objGetMessageObjGetMessageObj, get_message_paramget_message_paramGetMessageParamget_message_paramGetMessageParamGetMessageParam

Siehe auch

create_message_queuecreate_message_queueCreateMessageQueuecreate_message_queueCreateMessageQueueCreateMessageQueue, clear_message_queueclear_message_queueClearMessageQueueclear_message_queueClearMessageQueueClearMessageQueue, enqueue_messageenqueue_messageEnqueueMessageenqueue_messageEnqueueMessageEnqueueMessage, set_message_queue_paramset_message_queue_paramSetMessageQueueParamset_message_queue_paramSetMessageQueueParamSetMessageQueueParam, get_message_queue_paramget_message_queue_paramGetMessageQueueParamget_message_queue_paramGetMessageQueueParamGetMessageQueueParam, create_messagecreate_messageCreateMessagecreate_messageCreateMessageCreateMessage, clear_messageclear_messageClearMessageclear_messageClearMessageClearMessage, set_message_tupleset_message_tupleSetMessageTupleset_message_tupleSetMessageTupleSetMessageTuple, get_message_tupleget_message_tupleGetMessageTupleget_message_tupleGetMessageTupleGetMessageTuple, set_message_objset_message_objSetMessageObjset_message_objSetMessageObjSetMessageObj, get_message_objget_message_objGetMessageObjget_message_objGetMessageObjGetMessageObj

Modul

Foundation