class ara::core::Promise< void, E >

Die Spezialisierung ara::core::Promise< void, E > dient als asynchroner Erzeuger-Endpunkt zur Signalisierung des Abschlusses einer Operation ohne Rückgabewert oder zur Übertragung eines Fehlers ([SWS_CORE_06341]). Nach der Instanziierung wird über get_future() genau einmal das zugehörige Future für den Konsumenten abgerufen ([SWS_CORE_06344]). Die Bereitstellung erfolgt thread-safe durch set_value(), SetError() oder SetResult(), wodurch der gemeinsame Zustand als bereit markiert wird. Da die Klasse reine Move-Semantik besitzt, führen mehrfaches Setzen oder fehlende gemeinsame Zustände zu spezifizierten Verletzungen.

mehr ›

Kontext

Die Klasse ara::core::Promise< void, E > stellt eine Template-Spezialisierung für asynchrone Abläufe ohne Nutzdatenwert (Rückgabetyp void) dar. Sie bildet die Erzeugerseite (Producer) eines Kommunikationskanals und synchronisiert asynchrone Berechnungen oder Operationen mit der Konsumentenseite (Consumer). Über einen geteilten internen Zustand (Shared State) ermöglicht sie es, entweder den erfolgreichen Vollzug einer Operation oder das Auftreten eines Fehlers vom Typ E zu signalisieren. Das korrespondierende Empfänger-Objekt wird in Form von ara::core::Future< void, E > bereitgestellt ([SWS_CORE_06344]). Gemäß den Vorgaben der AUTOSAR Adaptive Platform erfordert die Implementierung, dass der Fehlertyp E mit ara::core::ErrorCode kompatibel ist; jede Abweichung führt zu einem Fehler bei der Kompilierung.

Lebenszyklus

Die Erzeugung einer Instanz erfolgt über den parameterlosen Standardkonstruktor [SWS_CORE_06341], welcher einen neuen gemeinsamen Zustand anlegt und sich analog zur C++-Standardfunktion std::promise verhält. Die Klasse modelliert eine exklusive Eigentümerschaft und implementiert strikte Move-Semantik: Sowohl der Kopierkonstruktor ([SWS_CORE_06350]) als auch der Kopierzuweisungsoperator ([SWS_CORE_06351]) sind gelöscht (delete).

Ein bestehender Zustand kann über den Move-Konstruktor ([SWS_CORE_06342]) oder den Move-Zuweisungsoperator ([SWS_CORE_06343]) auf andere Instanzen übertragen werden. Bei der Move-Zuweisung wird ein bis dahin gehaltener Shared State aufgegeben und der Zustand wie durch Promise(std::move(other)).swap(*this) übertragen ([SWS_CORE_06343]). Ferner erlaubt die Funktion swap ([SWS_CORE_06352]) den direkten Austausch zweier Zustände.

Der Destruktor [SWS_CORE_06349] gibt einen etwaigen noch gehaltenen Shared State frei. Interpretation: Das vorzeitige Aufgeben des Shared State bei der Zerstörung eines noch unbefriedigten Promises dürfte im verknüpften Future zu einem verwaisten Zustand führen. Frage Q-e89b32fa3e5994e2 (offen) Hinsichtlich der Nebenläufigkeit ist die Standard-Erzeugung ([SWS_CORE_06341]) sowie das Setzen des Ergebnisses ([SWS_CORE_06345], [SWS_CORE_06353], [SWS_CORE_06354], [SWS_CORE_06355], [SWS_CORE_06356]) thread-safe. Dagegen sind Move-Operationen, swap, das Abrufen des Futures ([SWS_CORE_06344]) und die Zerstörung nicht thread-safe und erfordern bei geteiltem Zugriff eine externe Koordination.

Nutzungspfad

Die typische Verwendung von ara::core::Promise< void, E > umfasst die Vorbereitung der asynchronen Ausführung, die Übergabe des Empfangskanals und die anschließende Ergebnismeldung:

1. Initialisierung: Der Erzeuger instanziiert das Promise-Objekt ([SWS_CORE_06341]).
2. Future abrufen: Über get_future() wird genau einmal das verknüpfte ara::core::Future< void, E > erzeugt ([SWS_CORE_06344]) und an die Konsumentenseite übergeben.
3. Ergebnis setzen: Nach Abschluss der asynchronen Operation versetzt der Erzeuger den gemeinsamen Zustand in den Bereit-Zustand (ready):
   • Im Erfolgsfall durch Aufruf von set_value() ohne Argumente ([SWS_CORE_06345]).
   • Im Fehlerfall durch Speichern eines Fehlers via SetError, entweder per Move ([SWS_CORE_06353]) oder per Kopie ([SWS_CORE_06354]).
   • Alternativ durch Übergabe eines vollständigen Result< void, E > mittels SetResult per Kopie ([SWS_CORE_06355]) oder Move ([SWS_CORE_06356]).
4. Auflösung: Sobald der Zustand bereit ist, kann der Konsument über das Future das Ergebnis konsumieren; das Promise-Objekt wird am Ende seines Geltungsbereichs freigegeben ([SWS_CORE_06349]).

Sequenzdiagramm: Typischer Ablauf der asynchronen Synchronisation von der Erzeugung bis zur Bereitstellung des Ergebnisses. Quellen: [SWS_CORE_06341], [SWS_CORE_06344], [SWS_CORE_06345], [SWS_CORE_06349]

Fehlerszenarien

Verletzungen der Vorbedingungen führen zu definierten Fehlersituationen (Violations):

• IsoStdFutureErrcFutureAlreadyRetrievedViolation: Wird ausgelöst, falls get_future() mehrfach für denselben gemeinsamen Zustand aufgerufen wird ([SWS_CORE_06344]).
• IsoStdFutureErrcNoStateViolation: Tritt auf, wenn get_future() aufgerufen wird, ohne dass das Promise über einen gemeinsamen Zustand verfügt ([SWS_CORE_06344]), etwa nach einer Move-Operation ([SWS_CORE_06342]).
• IsoStdFutureErrcPromiseAlreadySatisfiedViolation: Tritt ein, wenn set_value() ([SWS_CORE_06345]), SetError() ([SWS_CORE_06353], [SWS_CORE_06354]) oder SetResult() ([SWS_CORE_06355], [SWS_CORE_06356]) aufgerufen wird, obwohl im Shared State bereits ein Wert oder Fehler abgelegt ist.
• PromiseNoSharedStateToSetViolation: Signalisiert, dass set_value() ([SWS_CORE_06345]), SetError() ([SWS_CORE_06353], [SWS_CORE_06354]) oder SetResult() ([SWS_CORE_06355], [SWS_CORE_06356]) ohne existierenden gemeinsamen Zustand aufgerufen wurden.

Hinsichtlich der Ausnahme-Sicherheit sind die Methoden SetError und SetResult bedingt ausnahmesicher (conditionally exception safe): Sie garantieren noexcept nur dann, wenn der Typ E als nothrow-move-konstruierbar bzw. nothrow-copy-konstruierbar eingestuft ist ([SWS_CORE_06353], [SWS_CORE_06354], [SWS_CORE_06355], [SWS_CORE_06356]).