class ara::core::Future

Verwendung

Die Methode get() ruft synchron das Ergebnis vom Typ T aus einem ara::core::Future ab [SWS_CORE_00326]. Die Funktion verhält sich identisch zum Pendant in std::future; falls die asynchrone Berechnung noch andauert, blockiert der Aufruf bis zur Fertigstellung oder bis zum Auftreten eines Fehlers [SWS_CORE_00336]. Durch den Aufruf verliert das Objekt seinen Zustand, sodass das Future unmittelbar ungültig wird (valid() == false) [SWS_CORE_00326]. Ein blockierungsfreier Aufruf kann vorab über is_ready() abgesichert werden [SWS_CORE_00332].

Fehlerbehandlung

Fehlschläge werden über C++-Exceptions gemeldet [SWS_CORE_00326]:

• Wurde im zugeordneten Promise über SetError() oder SetResult() ein Fehler hinterlegt, wird eine Exception des entsprechenden Fehlertyps ausgelöst [SWS_CORE_00326].
• Wird der Shared State von der asynchronen Operation vorzeitig aufgegeben, resultiert dies im Fehler kBrokenPromise gemäß FutureErrc [SWS_CORE_00326], [SWS_CORE_00400].
• Erfolgt der Aufruf auf einer ungültigen Instanz, wird eine FutureException mit dem Fehlercode kNoState geworfen [SWS_CORE_00326].

Nebenläufigkeit und Einschränkungen

Die Operation ist weder threadsicher noch exceptionsicher (not exception safe) [SWS_CORE_00326]. Gleichzeitige Zugriffe auf dasselbe Future aus mehreren Threads erfordern externe Synchronisation. Sind Exceptions in der Compiler-Toolchain deaktiviert, nimmt get() nicht an der Überladungsauflösung teil [SWS_CORE_00326]; für diesen Fall existiert die exceptionsfreie Alternative GetResult() [SWS_CORE_00336]. Für Instanzen ohne Rückgabewert steht die Spezialisierung Future<void, E>::get() zur Verfügung [SWS_CORE_06226].

Die Elementfunktion then dient der Verkettung asynchroner Berechnungen und registriert ein aufrufbares Objekt func als Continuation an einer Instanz von ara::core::Future [SWS_CORE_00331]. Nach Rückkehr des Aufrufs ist die ursprüngliche Future ungültig (valid() == false). Das Aufrufziel erhält das über GetResult() bezogene Ergebnis der Instanz als Rvalue vom Typ Result<T, E> übergeben [SWS_CORE_00331].

Der Rückgabetyp von then richtet sich nach dem Rückgabetyp U der Continuation [SWS_CORE_00331]:

• Gibt func eine Future<T2, E2> zurück, erfolgt implizites Future-Unwrapping zu Future<T2, E2> [SWS_CORE_00331].
• Gibt func ein Result<T2, E2> zurück, erfolgt implizites Result-Unwrapping zu Future<T2, E2> [SWS_CORE_00331].
• In allen anderen Fällen ist der Rückgabetyp Future<U, E> [SWS_CORE_00331].

Die Ausführung von func kann synchron im Kontext des Aufrufs von then, im Kontext von Promise::set_result bzw. Promise::SetError oder in einem anderen Kontext stattfinden [SWS_CORE_00331]. Der Aufruf ist als nicht threadsicher spezifiziert. Die Continuation wird in der zurückgegebenen Future registriert; nach Rückkehr von deren Destruktor darf keine Continuation mehr ausgeführt werden, während eine bereits laufende Ausführung bis zum Ende läuft [SWS_CORE_00331].

Standardisierte Fehlercodes existieren nicht [SWS_CORE_00331]. Fehler müssen von Benutzern abgefangen und als Fehlercode in einem zurückgegebenen Result oder einer Future weitergereicht werden, da Ausnahmen die Continuation nicht verlassen dürfen. Ein Aufruf an einer ungültigen Future löst FutureInvalidViolation aus; wirft die Continuation eine Ausnahme, resultiert dies in FutureContinuationHasThrownViolation [SWS_CORE_00331].

Für Ausführungen in einem expliziten Ausführungskontext steht die Überladung mit Executor zur Verfügung [SWS_CORE_00337], während für Operationen ohne Rückgabewert die Void-Spezialisierung greift [SWS_CORE_06231].

Verwendung und Semantik

Die Methode then registriert eine Continuation (func), die asynchron im Kontext des übergebenen executor ausgeführt wird, sobald das Ergebnis der aktuellen Future-Instanz vorliegt [SWS_CORE_00337]. Die aufrufbare Einheit nimmt das Ergebnis der Instanz als Rvalue-Ausdruck vom Typ Result<T,E> entgegen [SWS_CORE_00337]. Der Rückgabetyp richtet sich nach dem Rückgabetyp U der Continuation:

• Gibt die Continuation ein Future<T2,E2> zurück, erfolgt ein implizites Entpacken zu Future<T2,E2> [SWS_CORE_00337].
• Gibt die Continuation ein Result<T2,E2> zurück, wird dieses ebenfalls implizit zu Future<T2,E2> aufgelöst [SWS_CORE_00337].
• In allen anderen Fällen liefert der Aufruf Future<U,E> [SWS_CORE_00337].

Nebenläufigkeit und Lebenszyklus

Unmittelbar nach Rückkehr des Methodenaufrufs ist die ursprüngliche Future-Instanz ungültig (valid() == false) [SWS_CORE_00337]. Die Funktion ist als nicht threadsicher deklariert [SWS_CORE_00337]. Registrierte Continuations werden im neu zurückgegebenen Future verwaltet. Nach Ablauf dessen Destruktors darf keine Continuation mehr gestartet werden; eine bereits laufende Ausführung wird zu Ende geführt, sodass der Destruktor blockieren kann [SWS_CORE_00337].

Fehlerbehandlung und Zusammenspiel

Standardisierte Fehlercodes sind nicht definiert [SWS_CORE_00337]. Ein Aufruf auf einer ungültigen Instanz löst die Violation FutureInvalidViolation aus [SWS_CORE_00337]. Wirft die Continuation eine Ausnahme, resultiert dies in einer FutureContinuationHasThrownViolation; Ausnahmen müssen daher abgefangen und als Fehler über ara::core::Result oder ara::core::Future weitergereicht werden [SWS_CORE_00337]. Gegenüber der Überladung ohne Ausführungskontext [SWS_CORE_00331] erzwingt diese Variante die Ausführung auf dem übergebenen Executor; für void-Ergebnistypen existiert die analoge Spezialisierung [SWS_CORE_06237].

Die synchrone Abfragefunktion valid() prüft ohne Parameter, ob eine Instanz von ara::core::Future einen geteilten Zustand (Shared State) besitzt und damit verwendbar ist [SWS_CORE_00327]. Sie liefert true zurück, falls das Objekt einsatzbereit ist, und false, wenn kein geteilter Zustand vorliegt [SWS_CORE_00327]. Das Verhalten entspricht der Standardfunktion std::future::valid und gilt in gleicher Weise für die Templatespezialisierung ara::core::Future<void, E> [SWS_CORE_06227].

Die Funktion ist als noexcept deklariert, gilt als ausnahmesicher (exception safe) und ist ausdrücklich als threadsicher (thread-safe) spezifiziert [SWS_CORE_00327]. Sie löst selbst keine Fehlercodes oder Exceptions aus und kann daher gefahrlos zur Zustandsprüfung herangezogen werden [SWS_CORE_00327].

Im Zusammenspiel mit anderen Methoden von Future ist die Validitätsprüfung entscheidend, da aufrufende Operationen wie wait() [SWS_CORE_00328] oder is_ready() [SWS_CORE_00332] bei ungültigem Zustand (valid() == false) eine FutureInvalidViolation auslösen. Ein zuvor gültiges Future wird automatisch ungültig, sobald sein Ergebnis über get() [SWS_CORE_00326] oder GetResult() [SWS_CORE_00336] konsumiert wird oder eine Weiterverarbeitung über then() [SWS_CORE_00331], [SWS_CORE_00337] registriert wurde.

Die Elementfunktion wait der Klasse ara::core::Future blockiert den aufrufenden Thread synchron, bis ein Ergebniswert oder ein Fehler aus der asynchronen Operation verfügbar ist [SWS_CORE_00328]. Die Funktion nimmt keine Parameter entgegen, liefert keinen Rückgabewert und verhält sich gemäß Spezifikation analog zur entsprechenden Funktion aus std::future [SWS_CORE_00328]. Dasselbe Verhalten gilt für die Template-Spezialisierung ara::core::Future<void, E> [SWS_CORE_06228].

Hinsichtlich Fehlerbehandlung und Nebenläufigkeit sind folgende Vorgaben definiert:

• Fehlerbedingung: Ist das Future-Objekt ungültig (valid == FALSE), liegt eine FutureInvalidViolation vor [SWS_CORE_00328], [SWS_CORE_06228]. Dennoch ist die Funktion als noexcept deklariert und als ausnahmesicher (exception safe) klassifiziert [SWS_CORE_00328].
• Thread-Sicherheit: Der Aufruf ist explizit als not thread-safe eingestuft [SWS_CORE_00328]. Ein nebenläufiger Zugriff auf dasselbe Future-Objekt ohne externe Synchronisation ist unzulässig.

Im Zusammenspiel mit verwandten Schnittstellen empfiehlt sich vor dem Aufruf die Prüfung mittels is_ready [SWS_CORE_00332], [SWS_CORE_06232]: Liefert diese true zurück, blockiert der Aufruf von wait garantiert nicht mehr. Ist statt unbegrenztem Warten ein zeitlich beschränkter Blockiervorgang gefordert, stehen alternativ wait_for mit einer relativen Zeitdauer [SWS_CORE_00329], [SWS_CORE_06229] sowie wait_until mit einem absoluten Zeitpunkt [SWS_CORE_00330], [SWS_CORE_06230] zur Verfügung.

Verwendung

Die Elementfunktion wait_for der Klasse ara::core::Future blockiert den aufrufenden Thread für maximal die übergebene Zeitspanne timeoutDuration oder bis ein Ergebniswert beziehungsweise ein Fehler im geteilten Zustand bereitsteht [SWS_CORE_00329]. Ihr Verhalten entspricht der korrespondierenden Funktion aus std::future [SWS_CORE_00329]. Als Rückgabewert liefert sie ein FutureStatus zurück [SWS_CORE_00329], das anzeigt, ob der geteilte Zustand verfügbar ist (kReady) oder die vorgegebene Wartezeit abgelaufen ist (kTimeout) [SWS_CORE_00361].

Fehlerbehandlung und Randbedingungen

Die Funktion ist als noexcept deklariert und als ausnahmesicher (exception safe) spezifiziert [SWS_CORE_00329]. Ist das Future-Objekt ungültig (valid == FALSE), liegt eine Verletzung in Form von FutureInvalidViolation vor [SWS_CORE_00329]. Interpretation: Da keine C++-Ausnahmen geworfen werden dürfen, dürfte eine solche Verletzung plattformseitig als fataler Laufzeitfehler behandelt werden. Frage Q-2f22a07f6e143856 (offen)

Nebenläufigkeit und Zusammenspiel

Die Operation ist als not thread-safe eingestuft [SWS_CORE_00329]; gleichzeitige Zugriffe auf dieselbe Instanz erfordern daher eine externe Synchronisation. Die Semantik und Signatur gelten identisch für die Template-Spezialisierung ara::core::Future<void, E> [SWS_CORE_06229]. Im Unterschied zu std::future_status existiert im Enumerationstyp FutureStatus kein Eintrag für deferred [SWS_CORE_00361].

Die Elementfunktion wait_until blockiert den aufrufenden Thread, bis entweder der angegebene absolute Zeitpunkt deadline erreicht ist oder das ara::core::Future ein Ergebnis bzw. einen Fehler bereitstellt [SWS_CORE_00330]. Das Verhalten orientiert sich an der korrespondierenden Funktion von std::future [SWS_CORE_00330].

Als Rückgabewert liefert die Funktion ein FutureStatus [SWS_CORE_00330]. Dieser Enum-Typ signalisiert über den Zustand kReady, dass der geteilte Zustand bereit ist (Wert oder Fehler verfügbar), oder über kTimeout, dass die Frist ohne Ergebnis verstrichen ist [SWS_CORE_00361]. Ein Zustand analog zu std::future_status::deferred existiert in FutureStatus nicht [SWS_CORE_00361].

Hinsichtlich der Fehlerbehandlung und Ausnahme-Sicherheit ist die Funktion als ausnahmesicher (exception safe) und noexcept spezifiziert [SWS_CORE_00330]. Wird die Funktion jedoch auf einer ungültigen Instanz aufgerufen (valid == FALSE), liegt eine Verletzung in Form von FutureInvalidViolation vor [SWS_CORE_00330].

Bezüglich der Nebenläufigkeit ist wait_until als nicht threadsicher (not thread-safe) eingestuft [SWS_CORE_00330]. Parallele Zugriffe auf dasselbe ara::core::Future-Objekt müssen daher extern synchronisiert werden. Dieselbe Semantik und Signatur gilt für die Spezialisierung ara::core::Future<void, E> [SWS_CORE_06230].