From ac8418c8a458b514fe65ef6a94ce8dba13067920 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 4 Dec 2025 17:08:18 +0300 Subject: [PATCH] docs: add project README Signed-off-by: NotAShelf Change-Id: I45a3fa9e4f1c8758b65e119e16e7b8a16a6a6964 --- README.md | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..14ed935 --- /dev/null +++ b/README.md @@ -0,0 +1,160 @@ +# Sin + +> 🙏 Forgive me father for I have simply inhibited. + +**S**imple **In**hibitor (Sin) watches `/proc` for processes matching your +patterns and inhibits system idle/sleep while they run. + +## Why + +Your system shouldn't sleep while you're watching a movie, compiling code, or +running a long task. Sin prevents that by talking to systemd-logind when your +processes are active. + +I think this is should be a part of the idle program itself, but I could not +find an idle daemon that supports this feature. Naturally I made one of my own. +You are welcome to use it if this fits your needs. It is easy to **S**imply +**In**hibit. + +This is an _alternative_ to handling inhbiting on a compositor level, and is +aimed to detect things a compositor generally cannot. In the case of, e.g., +desktop applications I recommend letting your compositor handling the inhibit. I +might also support this for Sin in the future. + +## How it works + +1. You tell Sin which processes to watch (e.g., `mpv`, `steam`, `ffmpeg`) +2. Sin scans `/proc` every few seconds looking for them +3. When found, it grabs a Systemd inhibitor lock +4. When they exit, it releases the lock +5. Your system can sleep again + +Great success! + +## Usage + +```bash +# Keep system awake while Firefox is running +sin -n firefox + +# Watch multiple processes +sin -n steam -n "wine " -n lutris + +# Prevent sleep (not just idle) while rendering +sin -n blender --what=sleep + +# Custom poll interval +sin -n mpv --poll=1.0 +``` + +### Options + +```plaintext +-n, --name PATTERN Process cmdline substring to watch (required, repeatable) +--what WHAT What to inhibit: idle, sleep, shutdown, etc. (default: idle) +--mode MODE block or delay (default: block) +--poll SECONDS How often to check (0.1-3600, default: 2.0) +-d, --daemon Run as daemon (fork to background) +-q, --quiet Suppress informational output +-v, --version Show version +-h, --help Show help +``` + +## Building + +```bash +make +sudo make install +``` + +Requires: + +- GCC or Clang +- libsystemd + +That's it. + +## Examples + +```bash +# Don't idle while gaming +sin -n steam -n wine + +# Keep system awake during long builds +sin -n "cargo build" -n "nix build" + +# Prevent sleep while watching videos +sin -n mpv -n vlc --what=sleep + +# Fast polling for responsive tasks +sin -n ffmpeg --poll=0.5 + +# Run as daemon +sin -d -n mpv -n vlc +``` + +## Running as a Service + +A systemd service file is provided in `vendor/sin.service`. Edit it to match +your needs: + +```bash +# Copy and customize the service file +sudo cp vendor/sin.service /etc/systemd/system/ +sudo nano /etc/systemd/system/sin.service # Edit the ExecStart line + +# Enable and start +sudo systemctl enable --now sin.service +``` + +## Why not just use...? + +### Systemd-inhibit + +There are a few alternative options that you could go with. Namely, Sin is +inspired by the operating principle of `systemd-inhibit` among those options, +but prefers an approach similar to EarlyOOM where you provide the programs that +you want to watch instead of launching the program with a systemd-inhibit +wrapper. + +### Caffeine + +While researching, I've noticed programs such as **caffeine** and +**caffeine-ng** but ultimately decided against those since they seem to be +hooking up to more specific APIs than Systemd's own. I also find Python to be +unsuitable for production, and have elected to use C for a smaller and faster +binary that is easier to bootstrap. + +If you _do_ use those tools, and would like to try out Sin but cannot make a +switch due to missing features, please do create an issue. While I do not wish +to support screenlocker-specific APIs, I am happy to implement more generic +features such as a tray icon. Maybe even support for other init systems in the +future. + +### Hand-written Systemd Service + +Sure, if you'd like to write one yourself. Sin is that Systemd service in my +case. Give it a try, maybe I've saved you from some code spent fixing a trivial +problem. + +## Attributions + +[Diniamo]: https://github.com/diniamo +[Wayhibit]: https://github.com/diniamo/wayhibitor + +This project was inspired partially by [Diniamo]'s [Wayhibit], which deserves +the primary attribution here. I'd also like to thank Systemd developers for +`systemd-inhibit`, which has inspired me to write this project and also for the +sd-bus API that makes Sin possible. + +## License + + + +[here]: https://interoperable-europe.ec.europa.eu/sites/default/files/custom-page/attachment/eupl_v1.2_en.pdf + +This project is made available under European Union Public Licence (EUPL) +version 1.2. See [LICENSE](LICENSE) for more details on the exact conditions. An +online copy is provided [here]. + +