Module single_instance 

Cross-platform single-instance process guard.

On startup a process tries to acquire an exclusive, non-blocking lock on a named file under the user’s data dir. Holding the lock keeps a second invocation of the same role from running — the GUI uses it to avoid a duplicate window, the background agent to avoid two processes fighting over the same devices and IPC socket. Each Role has its own lock file, so the GUI and the agent don’t lock each other out. The lock is released by the OS when the process exits, so crash-recovery is free: the next launch reclaims the lock on the leftover file without any cleanup ceremony.

Structs

InstanceGuard

Held by main for the duration of the run; dropped on exit (the OS releases the underlying file lock at the same time). The _handle field is intentionally unused — the value is alive only for its Drop side effect of closing the fd.

Enums

InstanceError

Failure acquiring the single-instance lock. InstanceError::AlreadyRunning is the expected “another copy is open” signal; every other variant indicates filesystem trouble.

Role

The processes that must run at most once per user, each on its own lock.

Functions

acquire

Acquire the single-instance lock for role (a file under paths::config_dir). Returns Ok(guard) on success — keep the guard alive until the process is about to exit.