klasse ara::core::Future< void, E >

De lidfunctie get van de specialisatie ara::core::Future<void, E> dient voor het wachten op het resultaat van een asynchrone bewerking zonder retourwaarde ([SWS_CORE_06226]). Deze gedraagt zich als de overeenkomstige functie van std::future en blokkeert de aanroeper totdat het resultaat of een fout beschikbaar is ([SWS_CORE_06226], [SWS_CORE_00336]). Na de aanroep verliest de Future-instantie haar geldigheid, zodat valid() == false geldt ([SWS_CORE_06226]).

De functie is als niet-uitzonderingsveilig (not exception safe) gedeclareerd ([SWS_CORE_06226]). Is in de gekoppelde Promise een fout opgeslagen, dan wordt er een overeenkomstige uitzondering gegenereerd ([SWS_CORE_06226]). Is de gedeelde toestand voortijdig opgegeven, dan treedt de foutcode kBrokenPromise conform [SWS_CORE_00400] op ([SWS_CORE_06226]). Wordt get op een reeds ongeldige instantie uitgevoerd, dan werpt de functie een FutureException op met de foutcode kNoState ([SWS_CORE_06226]).

Wat betreft de gelijktijdigheid is de methode niet thread-veilig (not thread-safe) ([SWS_CORE_06226]). Parallelle toegangen tot hetzelfde object vereisen daarom een externe synchronisatie. Bovendien neemt de functie niet deel aan de overbelastingsresolutie als C++-uitzonderingen in de compiler-toolchain zijn uitgeschakeld ([SWS_CORE_06226]).

In wisselwerking met verwante functies waarborgt [SWS_CORE_00332] (is_ready) dat get gegarandeerd niet blokkeert als de bewerking al voltooid is. Voor contexten zonder excepties biedt AUTOSAR als alternatief [SWS_CORE_00336] (GetResult), dat fouten via een resultaattype terugmeldt in plaats van excepties te werpen.

Gebruik

De methode then registreert een vervolgbewerking (continuation func) op een ara::core::Future<void, E>-instantie [SWS_CORE_06231]. Het aanroepbare object neemt het resultaat van de bewerking als rvalue-expressie van het type Result<void, E> in ontvangst, die intern via GetResult beschikbaar wordt gesteld [SWS_CORE_06231]. De aanroep van func kan synchroon in de context van then of asynchroon in de context van Promise::set_value(), Promise::SetError() dan wel elders plaatsvinden [SWS_CORE_06231].

Onmiddellijk na terugkeer uit then is de oorspronkelijke future ongeldig (valid() == false) [SWS_CORE_06231]. Het retourtype past zich aan het retourtype U van de continuation aan:

• Geeft func een Future<T2, E2> terug, dan vindt impliciet uitpakken plaats en geeft then Future<T2, E2> terug [SWS_CORE_06231].
• Geeft func een Result<T2, E2> terug, dan wordt deze eveneens impliciet uitgepakt tot Future<T2, E2> [SWS_CORE_06231].
• In alle andere gevallen is het retourtype Future<U, E> [SWS_CORE_06231].

Foutafhandeling en randvoorwaarden

Gestandaardiseerde foutcodes zijn voor deze functie niet gespecificeerd [SWS_CORE_06231]. De methode is gedeclareerd als noexcept, maar definieert twee schendingen (violations):

• FutureInvalidViolation: Treedt op wanneer de methode wordt aangeroepen op een ongeldige future (als valid() false teruggeeft) [SWS_CORE_06231].
• FutureContinuationHasThrownViolation: Treedt op wanneer de continuation een exceptie werpt die geen violation implementeert [SWS_CORE_06231]. Fouten in de continuation moeten in plaats daarvan verpakt in een Result of Future worden teruggegeven [SWS_CORE_06231].

Gelijktijdigheid en wisselwerking

De methode is niet thread-safe (not thread-safe) [SWS_CORE_06231]. Na terugkeer uit de destructor van de geretourneerde future wordt geen geregistreerde continuation meer uitgevoerd; een reeds lopende uitvoering wordt echter voltooid, zodat de destructor kan blokkeren [SWS_CORE_06231]. Terwijl [SWS_CORE_06231] geldt voor Future<void, E>, beschrijft [SWS_CORE_00331] de variant voor getypeerde futures Future<T, E> en [SWS_CORE_06237] de overload met expliciete executor.

De functie then registreert een aanroepbaar vervolgobject (continuation) func op een instantie van ara::core::Future<void, E> voor uitvoering in de opgegeven uitvoeringscontext executor [SWS_CORE_06237]. Onmiddellijk na het terugkeren van then verliest de aanroepende future-instantie haar geldigheid, zodat valid() == false is [SWS_CORE_06237]. De vervolgactie ontvangt het resultaat van de oorspronkelijke future-instantie als Result<void, E> in de vorm van een rvalue-expressie overgedragen [SWS_CORE_06237]. Als retourwaarde levert de aanroep een nieuwe Future-instantie op, waarbij retourtypen van de vervolgactie van het type Future<T2, E2> of Result<T2, E2> impliciet worden uitgepakt tot Future<T2, E2>; anders wordt een Future<U, E> geretourneerd [SWS_CORE_06237].

Met betrekking tot concurrency en levenscyclus is de functie gespecificeerd als niet thread-safe (not thread-safe) [SWS_CORE_06237]. De vervolgactie wordt geregistreerd in de nieuw geretourneerde future. Na terugkeer van de destructor van deze nieuwe future mag er geen vervolgactie meer worden uitgevoerd; een reeds in uitvoering zijnde vervolgactie loopt echter volledig ten einde, waardoor de destructor van de future kan blokkeren [SWS_CORE_06237].

De functie declareert geen gestandaardiseerde foutcodes en is gedefinieerd als noexcept [SWS_CORE_06237]. Wordt zij aangeroepen op een ongeldige future-instantie, dan is sprake van de overtreding FutureInvalidViolation [SWS_CORE_06237]. Indien de vervolgactie een exceptie genereert, leidt dit tot de overtreding FutureContinuationHasThrownViolation [SWS_CORE_06237]. Excepties mogen de vervolgactie niet verlaten, maar moeten desgewenst worden vertaald naar foutwaarden en binnen een Result of Future worden geretourneerd [SWS_CORE_06237]. De functie vult de executorloze variant [SWS_CORE_06231] aan en vormt de tegenhanger van de waardebevattende overbelastingen [SWS_CORE_00331] en [SWS_CORE_00337].

De functie valid() controleert synchroon of de instantie van ara::core::Future<void, E> een gedeelde toestand (shared state) bezit en daarmee bruikbaar is [SWS_CORE_06227]. Zij gedraagt zich conform de specificatie analoog aan de overeenkomstige functie uit std::future [SWS_CORE_06227]. Als retourwaarde levert zij true op wanneer de future bruikbaar is, en false wanneer deze niet bruikbaar is [SWS_CORE_06227].

Wat betreft gelijktijdigheid en foutafhandeling is de methode gedeclareerd als noexcept, uitzonderingsveilig (exception safe) en uitdrukkelijk gespecificeerd als thread-safe [SWS_CORE_06227]. Zij kan zodoende veilig worden aangeroepen vanuit gelijktijdige contexten.

In samenspel met andere operaties dient valid() voor het beveiligen van de levenscyclus:

• Wordt op een ongeldig future-object (valid() == false) een operatie zoals wait() [SWS_CORE_06228] of is_ready() [SWS_CORE_00332] aangeroepen, dan activeert dit de schending FutureInvalidViolation.
• Consumerende operaties invalideren het object: na een aanroep van get() is de future niet meer geldig, zodat opvolgende controles met valid() de waarde false opleveren [SWS_CORE_06226].
• Evenzo leiden doorgiften via then() [SWS_CORE_00331] of aanroepen van GetResult() [SWS_CORE_00336] ertoe dat het oorspronkelijke future-object onmiddellijk wordt geïnvalideerd.

De memberfunctie wait van de specialisatie ara::core::Future<void, E> blokkeert de aanroepende thread synchroon totdat het resultaat van de asynchrone bewerking in de vorm van een waarde of een fout beschikbaar is [SWS_CORE_06228]. De functie accepteert geen parameters, levert geen retourwaarde op (void) en gedraagt zich conform de specificatie zoals de overeenkomstige functie van std::future [SWS_CORE_06228].

Met betrekking tot foutafhandeling en randvoorwaarden gelden de volgende voorschriften:

• Exceptieveiligheid en foutafhandeling: De bewerking is gedeclareerd met noexcept en gespecificeerd als exceptieveilig (exception safe) [SWS_CORE_06228]. Levert valid() voor de future-instantie false op, dan is er sprake van de schending FutureInvalidViolation [SWS_CORE_06228]. Het concrete gevolg van deze schending is vermoedelijk gerealiseerd als systeemspecifieke foutafhandeling van de AUTOSAR-runtime-omgeving. Vraag Q-469e9abc947b9869 (open)
• Concurrentie: De functie is geclassificeerd als niet-thread-safe (not thread-safe) [SWS_CORE_06228]. Gelijktijdige toegang tot hetzelfde future-object zonder externe synchronisatie is daarom niet toegestaan.

In wisselwerking met de overige functies van de module core bestaan de volgende mogelijkheden:

• Met de thread-safe methode is_ready kan vooraf worden opgevraagd of de bewerking is voltooid; bij teruggave van true blokkeert wait gegarandeerd niet meer [SWS_CORE_06232].
• Om oneindig blokkeren te voorkomen, staan de tijdgebonden functies wait_for met een relatieve tijdsduur [SWS_CORE_06229] evenals wait_until met een absoluut tijdstip [SWS_CORE_06230] ter beschikking.
• Voor de primaire templateklasse ara::core::Future gelden dezelfde synchrone wachtvoorschriften en beperkingen [SWS_CORE_00328].

De methode wait_for van de specialisatie ara::core::Future<void, E> blokkeert de aanroepende thread synchroon gedurende een maximale tijdsduur timeoutDuration of totdat het resultaat beschikbaar is [SWS_CORE_06229]. Zij gedraagt zich semantisch zoals de corresponderende standaardfunctie std::future::wait_for [SWS_CORE_06229].

Als retourwaarde levert de functie de status FutureStatus [SWS_CORE_06229]. Deze signaleert met FutureStatus::kReady dat een waarde of een fout beschikbaar is, respectievelijk met FutureStatus::kTimeout dat de termijn zonder resultaat is verstreken [SWS_CORE_00361]. Een aan std::future_status::deferred equivalente toestand is niet voorzien [SWS_CORE_00361]. Het gedrag komt overeen met de algemene Future-interface [SWS_CORE_00329].

Voor de aanroep gelden de volgende voorwaarden met betrekking tot concurrency en foutafhandeling:

• Concurrency: De functie is gespecificeerd als niet thread-safe (not thread-safe) [SWS_CORE_06229]. Gelijktijdige aanroepen op dezelfde instantie moeten aan de zijde van de aanroeper worden beveiligd.
• Foutgevallen en exception safety: De bewerking is gedeclareerd als exceptieveilig (exception safe) alsmede noexcept [SWS_CORE_06229]. Als het Future-object ongeldig is (valid() levert false op), is er sprake van een FutureInvalidViolation [SWS_CORE_06229]. Vanwege de noexcept-declaratie zou deze overtreding vermoedelijk leiden tot een onmiddellijke programma-afbreking. Vraag Q-4f01aa6e7fbfb12d (open)

De lidfunctie wait_until van de specialisatie ara::core::Future<void, E> blokkeert de aanroepende thread totdat het opgegeven absolute tijdstip deadline is bereikt of een waarde respectievelijk een fout beschikbaar is [SWS_CORE_06230]. De functie vertoont hetzelfde gedrag als de corresponderende C++-standaardfunctie std::future::wait_until [SWS_CORE_06230] en bezit dezelfde semantiek als de generieke overbelasting voor ara::core::Future [SWS_CORE_00330].

De retourwaarde van het type FutureStatus signaleert of de termijn is bereikt of dat er een waarde beschikbaar is [SWS_CORE_06230]. Hierbij geeft de toestand kReady aan dat de gedeelde status gereed is, terwijl kTimeout betekent dat de gedeelde status vóór het verstrijken van de termijn niet gereed was [SWS_CORE_00361]. Een toestand analoog aan std::future_status::deferred bestaat niet in FutureStatus [SWS_CORE_00361].

Met betrekking tot uitvoering en randvoorwaarden zijn de volgende specificaties gedefinieerd:

• Aanroepcontext en uitzonderingsgedrag: De functie is beschikbaar via het headerbestand #include "ara/core/future.h", gedeclareerd als noexcept en gespecificeerd als exceptieveilig (exception safe) [SWS_CORE_06230].
• Fouttoestanden: Als de future ongeldig is, dus wanneer valid() de waarde false retourneert, is sprake van de overtreding FutureInvalidViolation [SWS_CORE_06230].
• Concurrency: De bewerking is geclassificeerd als niet thread-safe (not thread-safe) [SWS_CORE_06230].