Modul orbit_framework.messaging¶

Dieses Modul implementiert das Nachrichtensystem von ORBIT.

Das Modul umfasst die folgenden Klassen:

MessageBus
Slot
Listener
MultiListener

MessageBus¶

class orbit_framework.messaging.MessageBus(core)¶

Diese Klasse implementiert das ORBIT-Nachrichtensystem.

Parameter

core: Ein Verweis auf den Anwendungskern der ORBIT-Anwendung. Eine Instanz der Klasse Core.

Beschreibung

Das Nachrichtensystem funktioniert nach dem Broadcast-Prinzip. Nachrichten werden von einem Absender an das Nachrichtensystem übergeben, ohne dass der Absender weiß, wer die Nachricht empfangen wird (send()).

Empfänger können sich mit einem Empfangsmuster (Slot) bei dem Nachrichtensystem registrieren (add_listener()) und bekommen alle Nachrichten zugestellt, die ihrem Empfangsmuster entsprechen.

Das Zustellen der Nachrichten (der Aufruf der Empfänger-Callbacks) erfolgt in einem dedizierten Thread. Das hat den Vorteil, dass das Versenden einer Nachricht ein asynchroner Vorgang ist, der den Absender nicht blockiert.

Jede Nachricht ist einem Ereignis zugeordnet. Dieses Ereignis ist durch einen Job, eine Komponente und einen Ereignisnamen definiert. Der Absender eines Ereignisses gibt beim Versenden einer Nachricht den Namen des Ereignisses an.

Um das Erzeugen von Empfangsmustern (Slot) zu vereinfachen, können Jobs, Komponenten und Ereignisnamen zu Gruppen zusammengefasst werden (job_group(), component_group(), name_group()).

class Message(job, component, name, value)¶: Diese Klasse repräsentiert eine Nachricht im Nachrichtensystem. Sie wird nur intern verwendet.

MessageBus.add_listener(listener)¶

Registriert einen Empfänger mit einem Empfangsmuster im Nachrichtensystem.

Das Empfangsmuster besteht aus den drei Attributen job, component und name. Diese Attribute können jeweils einen Namen, einen Gruppennamen oder None enthalten. Sie werden benutzt, um zu entscheiden, ob eine Nachricht an den Empfänger übergeben wird oder nicht.

Üblichweise wird als Empfänger ein Listener-Objekt verwendet, welches mit einem Slot-Objekt und einem Callback initialisiert wurde.

Die Nachricht 
M: job = 'A', component = '1', name = 'a', value = ...
wird an alle Empfänger mit dem Empfangsmuster
〈 job = 'A', component = '1', name = 'a' 〉
übergeben.

Existiert eine Ereignisnamengruppe mit dem Namen 'x' und den Ereignisnamen 'a', b', 'c', wird die Nachricht M auch an alle Empfänger mit dem Empfangsmuster

〈 job = 'A', component = '1', name = 'x' 〉 übergeben.

Hat ein Attribut den Wert None, wird es ignoriert. Das bedeutet, die Nachricht M wird auch an alle Empfänger mit dem Empfangsmuster

〈 job = 'A', component = '1', name = None 〉 übergeben.

Der Empfänger muss den Aufruf als Funktion unterstützen. Er wird für die Übergabe der Nachricht mit den folgenden vier Parametern aufgerufen:

job: Der Name des versendenden Jobs
component: Der Name der versendenden Komponente
name: Der Name des Ereignisses
value: Der Nachrichteninhalt

Die Parameter werden in der dargestellten Reihenfolge als Positionsparameter übergeben.

Siehe auch: Slot, Listener, remove_listener(), send()

MessageBus.component_group(group_name, *names)¶

Richtet eine Absendergruppe auf Komponentenebene ein.

Parameter

group_name: Der Name der Gruppe.
names (var args): Die Namen der Komponenten, welche in der Gruppe zusammengefasst werden sollen.

Beschreibung

Durch eine Absendergruppe auf Komponentenebene kann ein Slot anstelle eines spezifischen Komponentennamens einen Gruppennamen im Empfangsmuster angeben.

Siehe auch: Slot, Listener, add_listener(), remove_listener(), orbit_framework.Job.add_listener(), orbit_framework.Component.add_listener()

MessageBus.job_group(group_name, *names)¶

Richtet eine Absendergruppe auf Job-Ebene ein.

Parameter

group_name: Der Name der Gruppe.
names (var args): Die Namen der Jobs, welche in der Gruppe zusammengefasst werden sollen.

Beschreibung

Durch eine Absendergruppe auf Job-Ebene kann ein Slot anstelle eines spezifischen Jobnamens einen Gruppennamen im Empfangsmuster angeben.

Siehe auch: Slot, Listener, add_listener(), remove_listener(), orbit_framework.Job.add_listener(), orbit_framework.Component.add_listener()

MessageBus.name_group(group_name, *names)¶

Richtet eine Absendergruppe auf Ereignisebene ein.

Parameter

group_name: Der Name der Gruppe.
names (var args): Die Namen der Ereignisse, welche in der Gruppe zusammengefasst werden sollen.

Beschreibung

Durch eine Absendergruppe auf Ereignisebene kann ein Slot anstelle eines spezifischen Ereignisnamens einen Gruppennamen im Empfangsmuster angeben.

Siehe auch: Slot, Listener, add_listener(), remove_listener(), orbit_framework.Job.add_listener(), orbit_framework.Component.add_listener()

MessageBus.remove_listener(listener)¶

Entfernt einen Empfänger und sein Empfangsmuster aus dem Nachrichtensystem.

Bemerkung

Es muss das gleiche Objekt übergeben werden, wie an add_listener() übergeben wurde.

Siehe auch: add_listener()

MessageBus.send(job, component, name, value)¶

Sendet eine Nachricht über das Nachrichtensystem.

Parameter

job: Der versendende Job
component: Die versendende Komponente
name: Der Ereignisname
value: Der Inhalt der Nachricht

Beschreibung

Die Nachricht wird in die Warteschlange eingestellt. Der Aufruf kehrt sofort wieder zum Aufrufer zurück.

Siehe auch: add_listener()

MessageBus.start()¶

Startet das Nachrichtensystem.

Zur Weiterleitung der Nachrichten wird ein dedizierter Thread gestartet.

Siehe auch: stop()

MessageBus.stop(immediate=False)¶

Beendet das Nachrichtensystem.

Parameter

immediate (optional): True wenn wartende Nachrichten nicht mehr abgearbeitet werden sollen, False wenn erst alle wartenden Nachrichten abgearbeitet werden sollen.

Blockiert solange bis der dedizierte Thread für die Nachrichtenverteilung beendet wurde und kehrt erst anschließend zum Aufrufer zurück.

Siehe auch: start()

MessageBus.trace(text)¶: Schreibt eine Nachverfolgungsmeldung mit dem Ursprung MessageBus auf die Konsole.

Slot¶

class orbit_framework.messaging.Slot(job, component, name, predicate=None, transformation=None)¶

Diese Klasse repräsentiert ein Empfangsmuster für das Nachrichtensystem.

Parameter

job: Der Name des versendenen Jobs ein Gruppenname oder None.
component: Der Name der versendenen Komponente, 'JOB', ein Gruppenname oder None.
name: Der Ereignisname, ein Gruppenname oder None.
predicate (optional): Ein Prädikat als zusätzlicher Filter für Nachrichten. Eine Funktion mit der Signatur (job, component, name, value), welche die Nachricht entgegennimmt und True oder False zurückgibt.
transformation (optional): Eine Funktion, welche den Inhalt der Nachricht entgegennimmt und einen umgewandelten Inhalt zurückkgibt.

Beschreibung

Das Empfangsmuster wird verwendet, um ein Callback für den Nachrichtenempfang im Nachrichtensystem zu registrieren. Das Empfangsmuster kann durch einen Aufruf der Methode listener() mit einem Callback zu einem Empfänger verknüpft werden.

Für die Erzeugung von Slot-Instanzen gibt es einige statische Factory-Methoden: for_job(), for_component() und for_name().

Siehe auch: listener(), Listener

component¶: Gibt den Namen der versendenden Komponente, 'JOB', einen Gruppennamen oder None zurück.

for_component(job, component)¶: Erzeugt ein Empfangsmuster, welches auf die Nachrichten aller Komponenten mit dem übergegebenen Namen passt. Es kann auch ein Gruppenname übergegen werden.

for_job(job)¶: Erzeugt ein Empfangsmuster, welches auf alle Nachrichten von einem Job passt. Es kann auch ein Gruppenname übergegen werden.

for_name(name)¶: Erzeugt ein Empfangsmuster, welches auf alle Nachrichten für das übergebene Ereignis passt. Es kann auch ein Gruppenname übergegen werden.

job¶: Gibt den Namen des versendenden Jobs, einen Gruppennamen oder None zurück.

listener(callback)¶

Erzeugt mit dem übergebenen Callback einen Empfänger.

Siehe auch: Listener

name¶: Gibt den Ereignisnamen, einen Gruppenname oder None zurück.

predicate¶: Gibt das Filterprädikat oder None zurück.

transformation¶: Gibt die Transformationsfunktion für den Nachrichteninhalt oder None zurück.

Listener¶

class orbit_framework.messaging.Listener(callback, slot)¶

Diese Klasse repräsentiert einen Empfänger für das Nachrichtensystem.

Parameter

callback: Das Callback welches beim Eintreffen einer passenden Nachricht aufgerufen werden soll. Die Funktion muss die folgende Signatur besitzen: (job, component, name, value). Wird eine dynamische Methode statt einer statischen Funktion übergeben, muss die Methode die folgende Signatur besitzen: (self, job, component, name, value).
slot: Ein Empfangsmuster für die Filterung der Nachrichten.

Ein Empfänger kann mit Hilfe der folgenden Methoden für den Nachrichtenempfang registriert werden: MessageBus.add_listener(), orbit_framework.Job.add_listener() und orbit_framework.Component.add_listener().

Siehe auch: Slot, MessageBus

component¶: Gibt den Namen der versendenden Komponente, 'JOB', einen Gruppennamen oder None zurück.

job¶: Gibt den Namen des versendenden Jobs, einen Gruppennamen oder None zurück.

name¶: Gibt den Ereignisnamen, einen Gruppenname oder None zurück.

receiver¶

Gibt die Bezeichnung des Empfängers zurück.

Die Bezeichnung wird beim Protokollieren der Nachrichten verwendet, um den Weg der Nachrichten kenntlich zu machen.

Werden die Methoden orbit_framework.Job.add_listener() oder orbit_framework.Component.add_listener() verwendet, wird dieses Attribut automatisch gesetzt. Wird der Empfänger direkt mit MessageBus.add_listener() registriert, sollte dieses Attribut vorher gesetzt werden, um den Empfänger zu bezeichnen.

MultiListener¶

class orbit_framework.messaging.MultiListener(name, callback)¶

Diese Klasse implementiert einen Mehrfachempfänger. Das ist ein Mechanismus für den Empfang von Nachrichten über das Nachrichtensystem, bei dem mehrere Empfangsmuster mit einem Callback verknüpft werden.

Parameter

name: Der Name des Empfängers.
callback: Eine Funktion die bei einem Nachrichtenempfang aufgerufen werden soll. Die Funktion muss die Signatur (job, component, name, value) besitzen.

Beschreibung

Der Mehrfachempfänger wird mit einem Namen und einem Callback initialisiert. Anschließend können mit add_slot() mehrere Empfangsmuster eingerichtet werden.

Bemerkung

Der Mehrfachempfänger erzeugt für jedes Empfangsmuster einen eigenen Empfänger. Passt eine Nachricht zu mehr als einem Empfangsmuster, wird das Callback für die Nachricht auch mehr als einmal aufgerufen.

Der Mehrfachempfänger muss mit dem Nachrichtensystem verknüpft werden, damit er funktioniert. Dazu wird die Methode activate() aufgerufen.

Siehe auch: Listener, add_slot(), activate()

activate(message_bus)¶: Verknüpft den Mehrfachempfänger mit dem Nachrichtensystem.

add_slot(slot)¶

Fügt ein Empfangsmuster hinzu.

Siehe auch: Slot

deactivate(message_bus)¶: Löst die Verbindung des Mehrfachempfängers vom Nachrichtensystem.

listeners¶: Gibt eine Sequenz mit allen zur Zeit erzeugten Empfängern zurück.

name¶: Gibt den Namen des Empfängers zurück.

remove_slot(slot)¶: Entfernt ein Empfangsmuster.

Bemerkung

Es muss die selbe Referenz auf das Empfangsmuster übergeben werden, wie an add_slot() übergeben wurde.

slots¶: Gibt eine Sequenz mit allen eingerichteten Empfangsmustern zurück.