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

De specialisatie ara::core::Promise< void, E > dient als asynchroon producent-eindpunt voor het signaleren van de voltooiing van een operatie zonder retourwaarde of voor het overdragen van een fout ([SWS_CORE_06341]). Na de instantiëring wordt via get_future() precies één keer de bijbehorende Future voor de consument opgehaald ([SWS_CORE_06344]). De beschikbaarstelling vindt thread-safe plaats via set_value(), SetError() of SetResult(), waardoor de gedeelde toestand als gereed wordt gemarkeerd. Aangezien de klasse zuivere move-semantiek heeft, leiden meervoudig instellen of ontbrekende gedeelde toestanden tot gespecificeerde schendingen.

meer ›

Context

De klasse ara::core::Promise< void, E > vormt een templatespecialisatie voor asynchrone processen zonder payloadwaarde (retourtype void). Deze vormt de producentzijde (producer) van een communicatiekanaal en synchroniseert asynchrone berekeningen of operaties met de consumentzijde (consumer). Via een gedeelde interne toestand (shared state) maakt ze het mogelijk om ofwel de succesvolle voltrekking van een operatie ofwel het optreden van een fout van het type E te signaleren. Het corresponderende ontvangerobject wordt beschikbaar gesteld in de vorm van ara::core::Future< void, E > ([SWS_CORE_06344]). Conform de voorschriften van het AUTOSAR Adaptive Platform vereist de implementatie dat het fouttype E compatibel is met ara::core::ErrorCode; elke afwijking leidt tot een fout bij het compileren.

Levenscyclus

De creatie van een instantie vindt plaats via de parameterloze standaardconstructor [SWS_CORE_06341], die een nieuwe gedeelde toestand aanmaakt en zich analoog gedraagt aan de C++-standaardfunctie std::promise. De klasse modelleert een exclusief eigendom en implementeert strikte move-semantiek: Zowel de copy-constructor ([SWS_CORE_06350]) als de copy-toewijzingsoperator ([SWS_CORE_06351]) zijn verwijderd (delete).

Een bestaande toestand kan via de move-constructor ([SWS_CORE_06342]) of de move-toekenningsoperator ([SWS_CORE_06343]) naar andere instanties worden overgedragen. Bij move-toekenning wordt een tot dan toe aangehouden shared state opgegeven en de toestand zoals door Promise(std::move(other)).swap(*this) overgedragen ([SWS_CORE_06343]). Bovendien maakt de functie swap ([SWS_CORE_06352]) de directe uitwisseling van twee toestanden mogelijk.

De destructor [SWS_CORE_06349] geeft een eventueel nog aangehouden shared state vrij. Interpretatie: het voortijdig opgeven van de shared state bij de vernietiging van een nog niet vervulde promise zal in de gekoppelde future vermoedelijk tot een verweesde toestand leiden. Vraag Q-e89b32fa3e5994e2 (open) Met betrekking tot gelijktijdigheid zijn de standaardaanmaak ([SWS_CORE_06341]) en het instellen van het resultaat ([SWS_CORE_06345], [SWS_CORE_06353], [SWS_CORE_06354], [SWS_CORE_06355], [SWS_CORE_06356]) thread-safe. Move-operaties, swap, het ophalen van de future ([SWS_CORE_06344]) en de vernietiging zijn daarentegen niet thread-safe en vereisen bij gedeelde toegang externe coördinatie.

Gebruikspad

Het typische gebruik van ara::core::Promise< void, E > omvat de voorbereiding van de asynchrone uitvoering, de overdracht van het ontvangstkanaal en de daaropvolgende resultaatmelding:

1. Initialisatie: De producent instantieert het promise-object ([SWS_CORE_06341]).
2. Future ophalen: Via get_future() wordt precies één keer de gekoppelde ara::core::Future< void, E > aangemaakt ([SWS_CORE_06344]) en aan de consumentenzijde overgedragen.
3. Resultaat instellen: Na voltooiing van de asynchrone bewerking brengt de producent de gedeelde toestand in de gereed-toestand (ready):
   • Bij succes door aanroep van set_value() zonder argumenten ([SWS_CORE_06345]).
   • Bij een fout door opslag van een fout via SetError, hetzij per move ([SWS_CORE_06353]), hetzij per kopie ([SWS_CORE_06354]).
   • Alternatief door overdracht van een volledige Result< void, E > middels SetResult per kopie ([SWS_CORE_06355]) of move ([SWS_CORE_06356]).
4. Afhandeling: Zodra de toestand gereed is, kan de consument via de future het resultaat consumeren; het promise-object wordt aan het einde van zijn geldigheidsbereik vrijgegeven ([SWS_CORE_06349]).

Sequentiediagram: Typisch verloop van de asynchrone synchronisatie van het aanmaken tot het beschikbaar stellen van het resultaat. Bronnen: [SWS_CORE_06341], [SWS_CORE_06344], [SWS_CORE_06345], [SWS_CORE_06349]

Foutscenario's

Schendingen van de preconditionele voorwaarden leiden tot gedefinieerde foutsituaties (violations):

• IsoStdFutureErrcFutureAlreadyRetrievedViolation: Wordt geactiveerd als get_future() herhaaldelijk voor dezelfde gedeelde toestand wordt aangeroepen ([SWS_CORE_06344]).
• IsoStdFutureErrcNoStateViolation: Treedt op wanneer get_future() wordt aangeroepen zonder dat de promise over een gedeelde toestand beschikt ([SWS_CORE_06344]), bijvoorbeeld na een move-operatie ([SWS_CORE_06342]).
• IsoStdFutureErrcPromiseAlreadySatisfiedViolation: Treedt op wanneer set_value() ([SWS_CORE_06345]), SetError() ([SWS_CORE_06353], [SWS_CORE_06354]) of SetResult() ([SWS_CORE_06355], [SWS_CORE_06356]) wordt aangeroepen, hoewel in de shared state al een waarde of fout is opgeslagen.
• PromiseNoSharedStateToSetViolation: Signaleert dat set_value() ([SWS_CORE_06345]), SetError() ([SWS_CORE_06353], [SWS_CORE_06354]) of SetResult() ([SWS_CORE_06355], [SWS_CORE_06356]) zonder bestaande gedeelde toestand zijn aangeroepen.

Wat betreft uitzonderingsveiligheid zijn de methoden SetError en SetResult voorwaardelijk uitzonderingsveilig (conditionally exception safe): ze garanderen noexcept alleen wanneer het type E als nothrow-move-construeerbaar resp. nothrow-copy-construeerbaar is geclassificeerd ([SWS_CORE_06353], [SWS_CORE_06354], [SWS_CORE_06355], [SWS_CORE_06356]).