enqueue_messageT_enqueue_messageEnqueueMessageEnqueueMessage (Operator)

Name

enqueue_messageT_enqueue_messageEnqueueMessageEnqueueMessage — Einreihen von Nachrichtenobjekten in eine Warteschlange.

Signatur

enqueue_message( : : QueueHandle, MessageHandle, GenParamName, GenParamValue : )

Beschreibung

enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessage reiht eine oder mehrere Nachrichtenobjekte in eine Warteschlange ein, die durch den Parameter QueueHandleQueueHandleQueueHandleQueueHandlequeueHandle referenziert wird. Die eingereihten Nachrichten können wieder durch den Operator dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessage der Reihe nach ausgelesen werden.

Die einzureihenden Nachrichtenobjekte (vgl. create_messagecreate_messageCreateMessageCreateMessageCreateMessage) werden im Parameter MessageHandleMessageHandleMessageHandleMessageHandlemessageHandle ü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_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessage 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_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessage wartet, erhält einer der wartenden Threads eine Nachricht und wird aufgeweckt, sobald ein Erzeugerthread mit Hilfe von enqueue_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessage 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_messageenqueue_messageEnqueueMessageEnqueueMessageEnqueueMessage kopiert die Nachricht in die Warteschlange, weshalb das ursprüngliche Nachrichtenobjekt danach sofort weiterverwendet werden kann, ohne das kopierte Nachrichtenobjekt zu beeinflussen.

Die Parameter GenParamNameGenParamNameGenParamNameGenParamNamegenParamName und GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue 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'"max_message_num""max_message_num""max_message_num""max_message_num" im Operator set_message_queue_paramset_message_queue_paramSetMessageQueueParamSetMessageQueueParamSetMessageQueueParam festgelegt.

Ausführungsinformationen

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

Parameter

QueueHandleQueueHandleQueueHandleQueueHandlequeueHandle (input_control) message_queue → (handle)

Warteschlangenobjekt.

Parameteranzahl: QueueHandle == 1

Restriktion: QueueHandle != 0

MessageHandleMessageHandleMessageHandleMessageHandlemessageHandle (input_control) message(-array) → (handle)

Einzureihende Nachrichtenobjekte.

Parameteranzahl: MessageHandle > 0

Restriktion: MessageHandle != 0

GenParamNameGenParamNameGenParamNameGenParamNamegenParamName (input_control) string-array → (string)

Namen generischer Parameter.

Parameteranzahl: GenParamName == GenParamValue

GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue (input_control) tuple-array → (string / integer / real)

Werte generischer Parameter.

Parameteranzahl: GenParamName == GenParamValue

Beispiel (HDevelop)

create_message_queue (Queue)
* ...
create_message (Message)
set_message_tuple (Message, 'mixed_tuple', ['The answer', 42])
enqueue_message (Queue, Message, [], [])

Ergebnis

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

Vorgänger

set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleSetMessageTuple, set_message_objset_message_objSetMessageObjSetMessageObjSetMessageObj

Siehe auch

create_message_queuecreate_message_queueCreateMessageQueueCreateMessageQueueCreateMessageQueue, clear_message_queueclear_message_queueClearMessageQueueClearMessageQueueClearMessageQueue, dequeue_messagedequeue_messageDequeueMessageDequeueMessageDequeueMessage, set_message_queue_paramset_message_queue_paramSetMessageQueueParamSetMessageQueueParamSetMessageQueueParam, get_message_queue_paramget_message_queue_paramGetMessageQueueParamGetMessageQueueParamGetMessageQueueParam, create_messagecreate_messageCreateMessageCreateMessageCreateMessage, clear_messageclear_messageClearMessageClearMessageClearMessage, set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleSetMessageTuple, get_message_tupleget_message_tupleGetMessageTupleGetMessageTupleGetMessageTuple, set_message_objset_message_objSetMessageObjSetMessageObjSetMessageObj, get_message_objget_message_objGetMessageObjGetMessageObjGetMessageObj

Modul

Foundation

Operatoren