klasse apext::sm::PowerStateInterface

De interface coördineert als OS-wrapper de energietoestanden tussen State Management en het besturingssysteem ([SWS_SM_71000]). State Management registreert hierlangs vooraf callback-handlers voor ontwaakgebeurtenissen en stuurt concrete statusverzoeken door naar het besturingssysteem ([SWS_SM_71001]). Na succesvolle reactivering kan de handler-registratie in de OS-wrapper weer ongedaan worden gemaakt. Als essentiële functionele randvoorwaarde geldt dat alle methode-aanroepen niet thread-safe zijn en daarom dwingend door de aanroeper moeten worden geserialiseerd.

meer ›

Context

De C++-klasse apext::sm::PowerStateInterface fungeert als functionele interface van de module State Management voor de coördinatie van energietoestanden met het besturingssysteem ([SWS_SM_71000], SWS StateManagement §C.1.2 “Class: PowerStateInterface”). In de systeemarchitectuur neemt zij de rol op zich van een OS-wrapper die verzoeken van State Management doorstuurt naar het onderliggende besturingssysteem en terugkoppelingen ontvangt. Bij de totale interactie zijn drie kerncomponenten betrokken: State Management als coördinerende instantie, de klasse PowerStateInterface als bemiddelaar en het host-besturingssysteem dat het hardwarematige energiebeheer uitvoert ([SWS_SM_71001]).

Contextdiagram: coördinatie van energietoestanden en ontwaaksignalen tussen State Management, OS-wrapper en besturingssysteem. Bronnen: [SWS_SM_71000], [SWS_SM_71001], [SWS_SM_71003].

Levenscyclus

Het aanmaken en vernietigen van instanties van de klasse PowerStateInterface is in de specificatiedocumenten niet geregeld via expliciete factory-methoden. Volgens interpretatie vindt de instantiëring vermoedelijk plaats door State Management tijdens de initialisatiefase daarvan om de OS-wrapper beschikbaar te stellen. Vraag Q-15bde6ce044e9bc3 (open) Voor het inbinden van de klasse is de header apext/sm/power_state_interface.h voorzien ([SWS_SM_71001], SWS StateManagement §C.1.2.1.1 “Member Functions”).

Wat betreft de interne toestand beheert het object de registratie van een handler voor ontwaakgebeurtenissen. Deze toestand blijft actief totdat de handler expliciet weer wordt verwijderd ([SWS_SM_71005]). Ten aanzien van concurrency zijn alle memberfuncties geclassificeerd als niet thread-safe (not-threadsafe) ([SWS_SM_71001], [SWS_SM_71003], [SWS_SM_71005]). Het aanroepende State Management moet daarom op eigen verantwoordelijkheid waarborgen dat aanroepen naar een instantie strikt worden geserialiseerd en dat er geen onbeschermde parallelle toegangen vanuit meerdere threads plaatsvinden.

Gebruikspad

Een typisch gebruikspad voor het aansturen van energietoestanden en het ontvangen van ontwaaksignalen voltrekt zich in meerdere op elkaar afgestemde stappen:

• Handler-registratie: voorafgaand aan het inleiden van een energiebesparingsstatus registreert State Management via RegisterWakeUpHandler een callback-functie van het type apext::sm::WakeUpHandler in de OS-wrapper ([SWS_SM_71003], SWS StateManagement §C.1.2.1.1.1 “RegisterWakeUpHandler”). Daarmee wordt vastgelegd hoe State Management over opvolgende ontwaakprocessen wordt geïnformeerd.
• Statusverzoek: vervolgens roept State Management de methode SetPowerState aan met de gewenste doelstatus apext::sm::PowerState ([SWS_SM_71001], SWS StateManagement §C.1.2.1.1.2 “SetPowerState”). De interface stuurt dit verzoek onmiddellijk door naar het besturingssysteem. De technische realisatie van de overgang vindt vermoedelijk platformspecifiek plaats in het besturingssysteem. Vraag Q-29345b74ba3bedf2 (open)
• Ontwaaknotificatie: detecteert het besturingssysteem een ontwaakgebeurtenis, dan wordt de melding doorgegeven aan de OS-wrapper. Deze voert de eerder geregistreerde WakeUpHandler uit. De aanroep vindt naar interpretatie vermoedelijk asynchroon plaats in de uitvoeringscontext van het reactiveringsproces. Vraag (open)
• Handler-deregistratie: zodra het ontwaakproces is voltooid of State Management geen verdere notificaties meer nodig heeft, wordt de geregistreerde callback via UnregisterWakeUpHandler verwijderd uit de OS-wrapper ([SWS_SM_71005], SWS StateManagement §C.1.2.1.1.3 “UnregisterWakeUpHandler”).

Sequentiediagram: typisch verloop van de handler-registratie, doorsturen van de toestand naar het besturingssysteem en deregistratie. Bronnen: [SWS_SM_71001], [SWS_SM_71003], [SWS_SM_71005].

Foutscenario's

De interfacemethoden RegisterWakeUpHandler, SetPowerState en UnregisterWakeUpHandler hebben het retourtype void en definiëren geen specifieke foutretourcodes ([SWS_SM_71001], [SWS_SM_71003], [SWS_SM_71005]). Alle functies zijn gedeclareerd als noexcept en garanderen volledige uitzonderingsveiligheid (exception safe).

Foutieve systeemtoestanden kunnen primair ontstaan door schendingen van precondities. Hiertoe behoort de schending van de vereiste thread-safety door onbeschermde parallelle methode-aanroepen. Daarnaast moet State Management als preconditie voor RegisterWakeUpHandler waarborgen dat het doorgegeven functie-object geldig is en tot de opheffing door UnregisterWakeUpHandler in het geheugen aanwezig blijft ([SWS_SM_71003], [SWS_SM_71005]).