README
¶
power
Keep the system awake, cgo-free. PreventSleep asks the OS not to idle-sleep
until you release the returned token — the keep-awake you want around a long
copy, a build, or media playback.
import "github.com/crgimenes/native/power"
tok, err := power.PreventSleep("ripping a disc")
if err != nil {
// errors.Is(err, power.ErrUnsupported) where there is no backend
log.Fatal(err)
}
defer tok.Release()
// ... do the long-running work; the machine won't idle-sleep ...
API
| Func | Description |
|---|---|
PreventSleep(reason string) (*Token, error) |
Inhibit idle system sleep until the token is released. reason is a short label some platforms surface (it becomes the macOS assertion name) and others ignore. |
(*Token) Release() error |
End the inhibition. Idempotent — extra or concurrent calls are safe no-ops. |
ErrUnsupported |
Sentinel returned by a platform with no backend (Linux). |
The token is the whole API surface. No native handles cross the boundary.
Platforms
| OS | Backend | Status |
|---|---|---|
| macOS | IOKit IOPMAssertionCreateWithName (PreventUserIdleSystemSleep) |
✅ |
| Windows | SetThreadExecutionState(ES_CONTINUOUS | ES_SYSTEM_REQUIRED) |
✅ builds + CI |
| Linux | — | ErrUnsupported |
Check the unsupported case with errors.Is(err, power.ErrUnsupported).
Why Linux is unsupported. There is no portable, cgo-free way to inhibit
sleep on Linux. The supported route is the systemd org.freedesktop.login1
Inhibit method, which hands back a file descriptor over D-Bus — and a
cgo-free D-Bus client means either a new dependency (this module avoids them) or
a hand-rolled wire-protocol client with SCM_RIGHTS fd passing, which is fragile
across distributions. Rather than ship something flaky, Linux returns a clear
ErrUnsupported. If a real need arrives, the login1 inhibitor (or shelling out
to systemd-inhibit) is the path.
Notes
- What is inhibited: idle system sleep. The display is still allowed to
sleep. (
PreventUserIdleSystemSleepon macOS;ES_SYSTEM_REQUIREDwithoutES_DISPLAY_REQUIREDon Windows.) - Effect vs. binding. A test can confirm the call succeeds and the token
round-trips, but not that the machine stayed awake. Verify the live effect by
hand:
pmset -g assertionson macOS,powercfg /requestson Windows, both of which list the active assertion while the example runs. - Battery / power-source state is not here. It is a separate, side-effect-free concern with no consumer yet; it can be added later behind its own call.
Example
A runnable demo (inhibit, hold a few seconds, release) lives in
examples/power:
go run ./examples/power
Conventions
Part of native; follows the shared shape — public API in a
tag-free power.go, per-platform power_darwin.go and power_windows.go, and a
power_other.go (!darwin && !windows) that returns ErrUnsupported so every
GOOS builds.
Documentation
¶
Overview ¶
Package power provides cgo-free control over system power behavior.
Today it does one thing: keep the system awake. PreventSleep asks the OS not to idle-sleep until the returned Token is released — the keep-awake you want around a long copy, a build, or media playback. Each platform binds the API the OS already ships, with no cgo and no bundled native libraries.
tok, err := power.PreventSleep("ripping a disc")
if err != nil {
// errors.Is(err, power.ErrUnsupported) on platforms with no backend
}
defer tok.Release()
Backends: macOS uses an IOKit power-management assertion, Windows uses SetThreadExecutionState. Linux has no portable cgo-free path (the systemd login1 inhibitor needs D-Bus, which this module deliberately avoids), so it returns ErrUnsupported.
Battery / power-source state is intentionally out of scope for now; it is a separate, side-effect-free concern and is not needed yet.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrUnsupported = errors.New("power: not supported on this platform")
ErrUnsupported is returned by PreventSleep on a platform that has no backend.
Functions ¶
This section is empty.
Types ¶
type Token ¶
type Token struct {
// contains filtered or unexported fields
}
Token represents one active sleep inhibition. Release it to let the system idle-sleep normally again.
func PreventSleep ¶
PreventSleep asks the OS to keep the system from idle-sleeping until the returned Token is released.
reason is a short human-readable label some platforms surface in their power tooling (it becomes the macOS assertion name) and others ignore. On a platform with no backend it returns ErrUnsupported and a nil Token.
Source Files