PowerAssertionController class final
Session-scoped owner of one power assertion. NOT a lifecycle-fidelity
port of oh-my-pi's #acquirePowerAssertion/#releasePowerAssertion:
oh-my-pi holds per session, but a session-open hold pins the machine
awake for whole idle hours between runs (issue #326) — so the DEFAULT
here is per-run (PowerAssertionHold.perRun): hosts fire
onRunStarted/onRunSettled around every run and the assertion
exists only while work is in flight. Session-held
(PowerAssertionHold.session) keeps oh-my-pi's behaviour as an
explicit opt-in via onSessionOpened/onSessionClosed. Both
directions stay idempotent and warn-not-crash: a failure on either
side is a WARNING — the run/session continues unguarded rather than
dying because the platform would not let us stay awake.
Constructors
- PowerAssertionController({required PowerAssertionRunner runner, required PowerAssertionLevel level, PowerAssertionHold hold = PowerAssertionHold.perRun, void onWarn(String message)?})
Properties
- acquired → bool
-
Whether an assertion was acquired and not yet released.
no setter
- hashCode → int
-
The hash code for this object.
no setterinherited
- hold → PowerAssertionHold
-
When the assertion is held (
power.hold): per-run by default, session as the explicit opt-in.final - level → PowerAssertionLevel
-
The configured sleep-prevention level.
final
- onWarn → void Function(String message)?
-
Receives best-effort warning lines ("power: ...") — never fatal.
final
- runner → PowerAssertionRunner
-
The platform runner (host-injected: real on the CLI/app, fake or
absent in tests).
final
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
Methods
-
acquire(
) → Future< void> -
Acquires the assertion for level. No-op for
offand when already acquired; a spawn failure warns (via the injected PowerAssertionControlleronWarn) and leaves the session unguarded. -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
onRunSettled(
) → Future< void> - Run-settle hook (PowerAssertionHold.perRun): releases once the run has fully settled (post-run compaction included).
-
onRunStarted(
) → void - Run-start hook (PowerAssertionHold.perRun): fires the acquisition without blocking the turn — sleep prevention is best-effort plumbing, never a reason to delay the first streamed byte.
-
onSessionClosed(
) → Future< void> - Session-close hook (BOTH modes): releases whatever is held — the per-run mode's safety net for an exit mid-run.
-
onSessionOpened(
) → Future< void> - Session-open hook (PowerAssertionHold.session): the explicit opt-in that holds the machine awake for the whole session, runs and idle stretches alike.
-
release(
) → Future< void> - Releases the assertion (idempotent; a failure warns, never throws).
-
status(
) → PowerAssertionStatus -
The
/powerstatus line. -
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited