Energy manager

The energy-manager module lets you control two forms of power behavior from Kotlin: lowering your app's CPU, I/O, and timer priority when it runs in the background, and preventing the display and system from sleeping during a long task. Both work on Windows, macOS, and Linux through the EnergyManager object.

Add the dependency

dependencies {
    implementation("dev.nucleusframework:nucleus.energy-manager:2.4.7")
}

Throttle a background window

Efficiency mode comes in two levels. Light mode deprioritizes CPU scheduling only; full mode also throttles I/O and, on macOS, network. Tie them to window state — light mode when the window loses focus, full mode when it is minimized:

import dev.nucleusframework.energymanager.EnergyManager

LaunchedEffect(state.isMinimized, isWindowFocused) {
    when {
        state.isMinimized -> {
            EnergyManager.disableLightEfficiencyMode()
            EnergyManager.enableEfficiencyMode()       // full — CPU and I/O throttled
        }
        !isWindowFocused -> {
            EnergyManager.disableEfficiencyMode()
            EnergyManager.enableLightEfficiencyMode()  // CPU only — I/O stays normal
        }
        else -> {
            EnergyManager.disableEfficiencyMode()
            EnergyManager.disableLightEfficiencyMode()
        }
    }
}

Run a coroutine with reduced priority

withEfficiencyMode runs a block on a dedicated background-priority thread and disposes the thread when the block returns. withLightEfficiencyMode applies process-level light QoS for the duration of the block, without pinning it to a thread:

// Dedicated low-priority thread (thread-level efficiency), I/O not throttled
val report = EnergyManager.withEfficiencyMode {
    computeHeavyReport()
}

// Process-level light QoS for the block — useful for batch I/O work
EnergyManager.withLightEfficiencyMode {
    syncDataFromServer()
    writeToDatabase()
}

Keep the system awake

Prevent sleep while a task or presentation runs, then release the request when it finishes. Choose whether the display must stay on:

import dev.nucleusframework.energymanager.AwakeMode
import dev.nucleusframework.energymanager.EnergyManager

// Presentation / kiosk — screen stays on (default)
EnergyManager.keepAwake(AwakeMode.SYSTEM_AND_DISPLAY)

// Long export / sync — machine stays awake; screen saver and display sleep behave normally
EnergyManager.keepAwake(AwakeMode.SYSTEM_ONLY)

// ... work completes
EnergyManager.releaseAwake()

Calling keepAwake while a request is already active replaces it with the new mode. keepScreenAwake() / releaseScreenAwake() / isScreenAwakeActive() remain as deprecated forwarders to keepAwake() / releaseAwake() / isAwakeActive().

How it works

Efficiency mode has two levels. Light mode leaves the app fully functional in the background: CPU scheduling is deprioritized through QoS hints, but I/O and network run at normal speed, so sync jobs and downloads still make progress. Full mode is meant for a minimized window where there is no UI to render — it adds I/O throttling and drops the process to the lowest priority class. Both are reversible immediately.

Thread-level efficiency applies the same mechanism to the calling thread only. It confines one heavy coroutine to the slow lane without slowing the rest of the process, which keeps a responsive UI alongside background work. The withEfficiencyMode helper builds on this by running its block on a single pinned thread.

Each platform maps these levels to native OS facilities:

Thread-level mode uses the per-thread form of these primitives on Linux, pthread_set_qos_class_self_np(QOS_CLASS_BACKGROUND) on macOS, and SetThreadInformation/THREAD_PRIORITY_IDLE on Windows.

API reference

EnergyManager

AwakeMode

Every enable/disable call and keepAwake/releaseAwake returns an EnergyManager.Result with success: Boolean, errorCode: Int, and message: String. On an unsupported platform the result is success = false with errorCode = -1.

Notes

• On Linux, libdbus-1, libX11, and libXss are loaded through dlopen() at runtime. Missing libraries degrade gracefully, and a private DBus connection is used so the module does not interfere with the JVM's accessibility bus. SYSTEM_ONLY needs a session bus (GNOME, PowerManagement) or systemd-logind; the X11 screen-saver fallback cannot serve that mode.
• On Windows 10 1709+, EcoQoS applies only on battery; Windows 11+ honors it on AC power too.
• For a long task that must also wake the device, hold keepAwake(…) alongside a job from the scheduler.

What's next

• Scheduler — run deferred and periodic background work.
• Taskbar progress — surface long-running task progress on the taskbar.
• Auto-launch — start your app at login.