klasse ara::core::Future

Gebruik

De methode get() haalt synchroon het resultaat van het type T op uit een ara::core::Future [SWS_CORE_00326]. De functie gedraagt zich identiek aan de tegenhanger in std::future; als de asynchrone berekening nog bezig is, blokkeert de aanroep tot voltooiing of tot er een fout optreedt [SWS_CORE_00336]. Door de aanroep verliest het object zijn toestand, zodat de future onmiddellijk ongeldig wordt (valid() == false) [SWS_CORE_00326]. Een niet-blokkerende aanroep kan vooraf worden gewaarborgd via is_ready() [SWS_CORE_00332].

Foutafhandeling

Fouten worden gemeld via C++-exceptions [SWS_CORE_00326]:

• Als in de toegewezen Promise via SetError() of SetResult() een fout is opgeslagen, wordt er een exceptie van het desbetreffende fouttype opgeworpen [SWS_CORE_00326].
• Wordt de shared state door de asynchrone operatie voortijdig opgegeven, dan resulteert dit in de fout kBrokenPromise conform FutureErrc [SWS_CORE_00326], [SWS_CORE_00400].
• Vindt de aanroep plaats op een ongeldige instantie, dan wordt een FutureException met de foutcode kNoState geworpen [SWS_CORE_00326].

Gelijktijdigheid en beperkingen

De operatie is noch thread-safe noch uitzonderingsveilig (not exception safe) [SWS_CORE_00326]. Gelijktijdige toegang tot dezelfde future vanuit meerdere threads vereist externe synchronisatie. Als excepties in de compiler-toolchain zijn uitgeschakeld, neemt get() niet deel aan overbelastingresolutie [SWS_CORE_00326]; voor dit geval bestaat het exceptievrije alternatief GetResult() [SWS_CORE_00336]. Voor instanties zonder retourwaarde is de specialisatie Future<void, E>::get() beschikbaar [SWS_CORE_06226].

De lidfunctie then dient voor het aaneenschakelen van asynchrone berekeningen en registreert een aanroepbaar object func als continuation op een instantie van ara::core::Future [SWS_CORE_00331]. Na terugkeer van de aanroep is de oorspronkelijke Future ongeldig (valid() == false). Het aanroepdoel ontvangt het via GetResult() verkregen resultaat van de instantie als rvalue van het type Result<T, E> [SWS_CORE_00331].

Het retourtype van then richt zich naar het retourtype U van de continuation [SWS_CORE_00331]:

• Geeft func een Future<T2, E2> terug, dan vindt impliciete future-unwrapping naar Future<T2, E2> plaats [SWS_CORE_00331].
• Geeft func een Result<T2, E2> terug, dan vindt impliciete result-unwrapping naar Future<T2, E2> plaats [SWS_CORE_00331].
• In alle andere gevallen is het retourtype Future<U, E> [SWS_CORE_00331].

De uitvoering van func kan synchroon in de context van de aanroep van then, in de context van Promise::set_result resp. Promise::SetError of in een andere context plaatsvinden [SWS_CORE_00331]. De aanroep is gespecificeerd als niet thread-safe. De continuation wordt geregistreerd in de geretourneerde Future; na terugkeer uit de destructor daarvan mag er geen continuation meer worden uitgevoerd, terwijl een reeds lopende uitvoering tot het einde wordt doorlopen [SWS_CORE_00331].

Gestandaardiseerde foutcodes bestaan niet [SWS_CORE_00331]. Fouten moeten door gebruikers worden opgevangen en als foutcode worden doorgegeven in een geretourneerde Result of Future, aangezien excepties de continuation niet mogen verlaten. Een aanroep op een ongeldige Future activeert FutureInvalidViolation; werpt de continuation een exceptie op, dan resulteert dit in FutureContinuationHasThrownViolation [SWS_CORE_00331].

Voor uitvoeringen in een expliciete uitvoeringscontext is de overbelasting met executor beschikbaar [SWS_CORE_00337], terwijl voor operaties zonder retourwaarde de void-specialisatie geldt [SWS_CORE_06231].

Gebruik en semantiek

De methode then registreert een continuation (func) die asynchroon wordt uitgevoerd in de context van de meegegeven executor zodra het resultaat van de actuele Future-instantie beschikbaar is [SWS_CORE_00337]. De aanroepbare eenheid neemt het resultaat van de instantie in ontvangst als een rvalue-expressie van het type Result<T,E> [SWS_CORE_00337]. Het retourtype is afhankelijk van het retourtype U van de continuation:

• Retourneert de continuation een Future<T2,E2>, dan vindt er een impliciet uitpakken naar Future<T2,E2> plaats [SWS_CORE_00337].
• Retourneert de continuation een Result<T2,E2>, dan wordt dit eveneens impliciet opgelost naar Future<T2,E2> [SWS_CORE_00337].
• In alle andere gevallen levert de aanroep Future<U,E> op [SWS_CORE_00337].

Gelijktijdigheid en levenscyclus

Onmiddellijk na terugkeer van de methode-aanroep is de oorspronkelijke Future-instantie ongeldig (valid() == false) [SWS_CORE_00337]. De functie is gedeclareerd als niet-thread-safe [SWS_CORE_00337]. Geregistreerde continuations worden beheerd in de nieuw geretourneerde Future. Na afloop van de destructor daarvan mag er geen continuation meer worden gestart; een reeds lopende uitvoering wordt voltooid, waardoor de destructor kan blokkeren [SWS_CORE_00337].

Foutafhandeling en wisselwerking

Gestandaardiseerde foutcodes zijn niet gedefinieerd [SWS_CORE_00337]. Een aanroep op een ongeldige instantie activeert de violation FutureInvalidViolation [SWS_CORE_00337]. Werpt de continuation een exceptie op, dan resulteert dit in een FutureContinuationHasThrownViolation; uitzonderingen moeten daarom worden opgevangen en als fout via ara::core::Result of ara::core::Future worden doorgegeven [SWS_CORE_00337]. Ten opzichte van de overbelasting zonder uitvoeringscontext [SWS_CORE_00331] dwingt deze variant de uitvoering op de meegegeven executor af; voor void-resultaattypen bestaat de analoge specialisatie [SWS_CORE_06237].

De synchrone opvraagfunctie valid() controleert zonder parameters of een instantie van ara::core::Future een gedeelde toestand (shared state) bezit en daarmee bruikbaar is [SWS_CORE_00327]. Deze levert true terug indien het object gereed is voor gebruik, en false wanneer er geen gedeelde toestand aanwezig is [SWS_CORE_00327]. Het gedrag komt overeen met de standaardfunctie std::future::valid en geldt op gelijke wijze voor de templatespecialisatie ara::core::Future<void, E> [SWS_CORE_06227].

De functie is gedeclareerd als noexcept, geldt als exceptieveilig (exception safe) en is uitdrukkelijk gespecificeerd als thread-safe (thread-safe) [SWS_CORE_00327]. Deze veroorzaakt zelf geen foutcodes of excepties en kan daarom veilig worden gebruikt voor tostandscontrole [SWS_CORE_00327].

In het samenspel met andere methoden van Future is de geldigheidscontrole cruciaal, aangezien aanroepende operaties zoals wait() [SWS_CORE_00328] of is_ready() [SWS_CORE_00332] bij een ongeldige toestand (valid() == false) een FutureInvalidViolation veroorzaken. Een voorheen geldige Future wordt automatisch ongeldig zodra het resultaat ervan via get() [SWS_CORE_00326] of GetResult() [SWS_CORE_00336] wordt geconsumeerd of verdere verwerking via then() [SWS_CORE_00331], [SWS_CORE_00337] is geregistreerd.

De elementfunctie wait van de klasse ara::core::Future blokkeert de aanroepende thread synchroon totdat er een resultaatwaarde of een fout uit de asynchrone operatie beschikbaar is [SWS_CORE_00328]. De functie accepteert geen parameters, levert geen retourwaarde op en gedraagt zich volgens de specificatie analoog aan de overeenkomstige functie uit std::future [SWS_CORE_00328]. Hetzelfde gedrag geldt voor de template-specialisatie ara::core::Future<void, E> [SWS_CORE_06228].

Met betrekking tot foutafhandeling en gelijktijdigheid zijn de volgende specificaties gedefinieerd:

• Foutconditie: Als het future-object ongeldig is (valid == FALSE), is er sprake van een FutureInvalidViolation [SWS_CORE_00328], [SWS_CORE_06228]. Desondanks is de functie gedeclareerd als noexcept en geclassificeerd als uitzonderingsveilig (exception safe) [SWS_CORE_00328].
• Thread-safety: De aanroep is expliciet aangemerkt als not thread-safe [SWS_CORE_00328]. Gelijktijdige toegang tot hetzelfde future-object zonder externe synchronisatie is niet toegestaan.

In het samenspel met verwante interfaces verdient het aanbeveling om voorafgaand aan de aanroep te controleren met is_ready [SWS_CORE_00332], [SWS_CORE_06232]: als deze true retourneert, blokkeert de aanroep van wait gegarandeerd niet meer. Is in plaats van onbeperkt wachten een in tijd beperkte blokkering vereist, dan staan als alternatief wait_for met een relatieve tijdsduur [SWS_CORE_00329], [SWS_CORE_06229] alsook wait_until met een absoluut tijdstip [SWS_CORE_00330], [SWS_CORE_06230] ter beschikking.

Gebruik

De memberfunctie wait_for van de klasse ara::core::Future blokkeert de aanroepende thread maximaal gedurende het meegegeven tijdsinterval timeoutDuration of totdat een resultaatwaarde respectievelijk een fout in de gedeelde toestand gereedstaat [SWS_CORE_00329]. Het gedrag ervan komt overeen met de corresponderende functie uit std::future [SWS_CORE_00329]. Als retourwaarde levert ze een FutureStatus op [SWS_CORE_00329], die aangeeft of de gedeelde toestand beschikbaar is (kReady) of dat de vooraf bepaalde wachttijd is verstreken (kTimeout) [SWS_CORE_00361].

Foutafhandeling en randvoorwaarden

De functie is gedeclareerd als noexcept en gespecificeerd als uitzonderingsveilig (exception safe) [SWS_CORE_00329]. Als het Future-object ongeldig is (valid == FALSE), is er sprake van een schending in de vorm van FutureInvalidViolation [SWS_CORE_00329]. Interpretatie: Aangezien er geen C++-uitzonderingen mogen worden geworpen, wordt een dergelijke schending aan de platformzijde vermoedelijk afgehandeld als een fatale runtimefout. Vraag Q-2f22a07f6e143856 (open)

Gelijktijdigheid en wisselwerking

De operatie is geclassificeerd als not thread-safe [SWS_CORE_00329]; gelijktijdige toegang tot dezelfde instantie vereist daarom externe synchronisatie. De semantiek en signatuur gelden identiek voor de template-specialisatie ara::core::Future<void, E> [SWS_CORE_06229]. In tegenstelling tot std::future_status bestaat er in het enumeratietype FutureStatus geen invoer voor deferred [SWS_CORE_00361].

De memberfunctie wait_until blokkeert de aanroepende thread totdat het opgegeven absolute tijdstip deadline is bereikt of de ara::core::Future een resultaat c.q. een fout gereedstelt [SWS_CORE_00330]. Het gedrag is gebaseerd op de corresponderende functie van std::future [SWS_CORE_00330].

Als retourwaarde levert de functie een FutureStatus op [SWS_CORE_00330]. Dit enum-type signaleert via de toestand kReady dat de gedeelde toestand gereed is (waarde of fout beschikbaar), of via kTimeout dat de termijn zonder resultaat is verstreken [SWS_CORE_00361]. Een toestand analoog aan std::future_status::deferred bestaat in FutureStatus niet [SWS_CORE_00361].

Wat betreft foutafhandeling en uitzonderingsveiligheid is de functie gespecificeerd als uitzonderingsveilig (exception safe) en noexcept [SWS_CORE_00330]. Wordt de functie echter op een ongeldige instantie aangeroepen (valid == FALSE), dan is er sprake van een schending in de vorm van FutureInvalidViolation [SWS_CORE_00330].

Met betrekking tot gelijktijdigheid is wait_until geclassificeerd als niet thread-veilig (not thread-safe) [SWS_CORE_00330]. Parallelle toegang tot hetzelfde ara::core::Future-object moet daarom extern worden gesynchroniseerd. Dezelfde semantiek en signatuur gelden voor de specialisatie ara::core::Future<void, E> [SWS_CORE_06230].