README
- ::equalKeepAwakeError::equal
- ::not_equalKeepAwakeError::not_equal
- ::outputKeepAwakeError::output
- ::to_stringKeepAwakeError::to_string
- ::activeGuard::active
- ::releaseGuard::release
- ::scopeGuard::scope
- ::equalScope::equal
- ::not_equalScope::not_equal
- ::outputScope::output
- ::to_reprScope::to_repr
- ::to_stringScope::to_string
V
acquire
V
default_reason
V
with_keepawake

proton_keepawake

Native keep-awake guards for MoonBit on Windows, Linux, and macOS.

keepawake

native

windows

linux

macos

power-management

Download zip

Author

moonbit-community

Version

0.6.0

License

Apache-2.0

Repository

github.com/moonbit-community/proton/tree/main/sys/keepawake

Last updated

9 hours ago

Downloads

23K

#keepawake

Native keep-awake guards for MoonBit. See README.md for platform requirements, ownership and migration details.

///|
test {
  assert_eq(
    @proton_keepawake.Scope::PreventSystemSleep.to_string(),
    "PreventSystemSleep",
  )
}

Use the async scoped API for work that must remain protected:

@proton_keepawake.with_keepawake(
  () => export_files(),
  reason="Exporting files",
)

Or acquire a guard owned by an existing task group:

@async.with_task_group(tasks => {
  let keep_guard = @proton_keepawake.acquire(tasks, reason="Exporting files")
  defer keep_guard.release()
  export_files()
})

The work starts after inhibition is acquired. Scope exit releases it; Linux helper loss fails with_keepawake and cancels its work. Both acquisition and release yield while waiting for the Linux backend.

KeepAwakeError

source

pub(all) suberror KeepAwakeError {
  BackendUnavailable(detail~ : String)
  OperationFailed(operation~ : String, detail~ : String)
} derive(Eq)

Describes failures raised by the native keep-awake backends.

BackendUnavailable means the current environment cannot offer the requested inhibition mechanism, while OperationFailed means a supported backend was found but the requested operation still failed.

Use the variant payloads to surface actionable diagnostics to callers or end users:

BackendUnavailable(detail~) reports that the current environment does not expose a usable keep-awake mechanism, for example because systemd-inhibit is missing or the expected macOS framework cannot be loaded.
OperationFailed(operation~, detail~) reports that the selected backend exists but could not complete the requested lifecycle action such as acquire or release.

The detail strings are intentionally human-readable, so they can be logged directly or attached to higher-level application errors without extra translation.

impl Show for KeepAwakeError

fn output(self : KeepAwakeError, logger : &Logger) -> Unit

source

Formats a keep-awake error into a stable diagnostic string.

The output is designed for logs, test assertions, and user-facing fallback diagnostics where a structured payload is not convenient to carry around. Each variant includes its labeled fields so the rendered text remains easy to scan when attached to higher-level error reports.

KeepAwakeError::equal

source

fn KeepAwakeError::equal(KeepAwakeError, KeepAwakeError) -> Bool

KeepAwakeError::not_equal

source

fn KeepAwakeError::not_equal(x : KeepAwakeError, y : KeepAwakeError) -> Bool

KeepAwakeError::output

source

fn KeepAwakeError::output(self : KeepAwakeError, logger : &Logger) -> Unit

KeepAwakeError::to_string

source

fn KeepAwakeError::to_string(self : KeepAwakeError) -> String

Guard

source

pub struct Guard {
  // private fields
}

A keep-awake request owned by the task group passed to acquire. Explicit release ends it early; leaving the group also releases it.

Guard::active

source

fn Guard::active(self : Guard) -> Bool

Reports whether inhibition remains active. A Linux helper that has exited is inactive even if release has not been called. This is a point-in-time observation; with_keepawake also monitors helper exit during scoped work.

Guard::release

source

async fn Guard::release(self : Guard) -> Unit raise KeepAwakeError + nocancel

Releases inhibition and awaits Linux helper cleanup without blocking the event loop. Safe to call repeatedly and during cancellation cleanup. Failed native release can be retried without cancelling the owning group.

Guard::scope

source

fn Guard::scope(self : Guard) -> Scope

Returns the requested scope.

Scope

source

pub(all) enum Scope {
  PreventSystemSleep
  PreventDisplaySleep
  PreventSystemAndDisplaySleep
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Describes which kind of idle policy should be inhibited while a guard is alive.

PreventSystemSleep asks the operating system to keep the machine awake. PreventDisplaySleep asks the operating system to keep the display awake. PreventSystemAndDisplaySleep requests both when the backend supports both concepts directly.

Choose the smallest scope that matches the protected work:

use PreventSystemSleep for background work such as builds, exports, or downloads where the display may still turn off
use PreventDisplaySleep for presentation-style tasks where the screen must remain visible
use PreventSystemAndDisplaySleep when both machine sleep and display sleep would interrupt the task

Backends may map these variants to different native APIs, but the semantic meaning of each variant stays stable across operating systems.

Example

test {
  assert_eq(
    @proton_keepawake.Scope::PreventSystemAndDisplaySleep.to_string(),
    "PreventSystemAndDisplaySleep",
  )
}

impl Show for Scope

fn output(self : Scope, logger : &Logger) -> Unit

source

Formats a scope using the stable public variant name.

The rendered form is intentionally identical to the enum case name so logs, examples, and snapshot tests can refer to the same terminology that callers use at the API boundary.

Scope::equal

source

fn Scope::equal(Scope, Scope) -> Bool

Scope::not_equal

source

fn Scope::not_equal(x : Scope, y : Scope) -> Bool

Scope::output

source

fn Scope::output(self : Scope, logger : &Logger) -> Unit

Scope::to_repr

source

fn Scope::to_repr(Scope) -> @moonbitlang/core/debug.Repr
Repr

Scope::to_string

source

fn Scope::to_string(self : Scope) -> String

acquire

source

async fn[G] acquire(group : @moonbitlang/async.TaskGroup
TaskGroup[G], reason? : String, scope? : Scope) -> Guard raise KeepAwakeError

Acquires inhibition before returning. The task group owns its lifetime. Linux waits asynchronously for systemd-inhibit to acquire the lock; missing or failing backends raise KeepAwakeError. Cancellation stops and reaps the helper. Callers can impose a startup deadline with @async.with_timeout. macOS and Windows retain their native power assertions. On Windows, acquire and release must run on the same OS thread.

default_reason

source

let default_reason : String

The reason used when callers supply an empty or whitespace-only reason.

with_keepawake

source

async fn[T] with_keepawake(action : async () -> T, reason? : String, scope? : Scope) -> T

Runs asynchronous work after acquiring inhibition, then releases it on return, error or cancellation. On Linux, unexpected helper exit fails this scope and cancels the work. No manual task group or guard is needed.

Source Files

Site source Report issue Packages Build queue Skills Statistics

proton_keepawake

#keepawake

#KeepAwakeError

#KeepAwakeError::equal

#KeepAwakeError::not_equal

#KeepAwakeError::output

#KeepAwakeError::to_string

#Guard

#Guard::active

#Guard::release

#Guard::scope

#Scope

Example

#Scope::equal

#Scope::not_equal

#Scope::output

#Scope::to_repr

#Scope::to_string

#acquire

#default_reason

#with_keepawake

Source Files

KeepAwakeError

KeepAwakeError::equal

KeepAwakeError::not_equal

KeepAwakeError::output

KeepAwakeError::to_string

Guard

Guard::active

Guard::release

Guard::scope

Scope

Scope::equal

Scope::not_equal

Scope::output

Scope::to_repr

Scope::to_string

acquire

default_reason

with_keepawake