|
| 1 | +## flux |
| 2 | +A daemon for X11 designed to automatically limit CPU usage of unfocused windows and run commands on focus and unfocus events. |
| 3 | + |
| 4 | +### Navigation |
| 5 | +- [Dependencies](#dependencies) |
| 6 | +- [Installation](#installation) |
| 7 | +- [Usage](#usage) |
| 8 | + - [Autostart](#autostart) |
| 9 | +- [Configuration](#configuration) |
| 10 | + - [Config path](#config-path) |
| 11 | + - [Limitations](#limitations) |
| 12 | + - [Configuration example](#configuration-example) |
| 13 | +- [Possible questions](#possible-questions) |
| 14 | + |
| 15 | +### Dependencies |
| 16 | +Developed and tested on Arch Linux, all dependencies below related to that and based on distros. |
| 17 | +- bash (tested with 5.2.032) |
| 18 | +- util-linux (tested with 2.40.2) |
| 19 | + - kill |
| 20 | +- procps-ng (tested with 4.0.4) |
| 21 | + - pkill |
| 22 | +- cpulimit (tested with 1:0.2) |
| 23 | + - cpulimit |
| 24 | +- coreutils (tested with 9.5) |
| 25 | + - nohup |
| 26 | + - readlink |
| 27 | + - sleep (optional, uses 'read -t \<seconds\>' by default) |
| 28 | +- xorg-xprop (tested with 1.2.7) |
| 29 | + - xprop |
| 30 | + |
| 31 | +### Installation |
| 32 | +This daemon was developed with portability in mind, so all code has been placed in one file. |
| 33 | +All you need is just download [flux](https://github.com/itz-me-zappex/flux/blob/main/flux) file, make it executable and put in place you want, but preferably put it somewhere in $PATH to avoid calling daemon with directly specified path every time. |
| 34 | + |
| 35 | +### Usage |
| 36 | +``` |
| 37 | +Usage: flux [option] <value> |
| 38 | +Options and values: |
| 39 | + -c, --config <path-to-config> Specify path to config file |
| 40 | + -h, --help Display this help |
| 41 | + -H, --hot Apply actions to already unfocused windows before handling events |
| 42 | + -l, --lazy Avoid focus and unfocus commands on hot |
| 43 | + -q, --quiet Print errors and warnings only |
| 44 | + -u, --usage Same as '--help' |
| 45 | + -v, --verbose Detailed output |
| 46 | + -V, --version Display release information |
| 47 | +``` |
| 48 | + |
| 49 | +#### Autostart |
| 50 | +Just add command to autostart using your DE settings or WM config. Running daemon as root also possible, but that feature almost useless. |
| 51 | + |
| 52 | +### Configuration |
| 53 | +A simple INI is used for configuration. |
| 54 | +Available keys and description: |
| 55 | +| Key | Description | |
| 56 | +|-------------------|-------------| |
| 57 | +| `name` | Name of process, gets from `/proc/<PID>/comm`, required if `executable` is not specified. | |
| 58 | +| `executable` | Path to binary of process, gets by reading `/proc/<PID>/exe` symlink, required if `name` is not specified. | |
| 59 | +| `owner` | User ID of process, gets from `/proc/<PID>/status`. | |
| 60 | +| `cpulimit` | CPU-limit between 0 and CPU threads multiplied by 100 (i.e. 2 threads = 200, 8 = 800 etc.), defaults to -1 which means no CPU-limit. | |
| 61 | +| `delay` | Delay before applying CPU-limit, required for avoid freezing app on exit keeping zombie process or longer exiting than should be, which caused by interrupts from 'cpulimit' subprocess. | |
| 62 | +| `focus` | Command to execute on focus event, command runs via bash and won't be killed on daemon exit, output is hidden for avoid mess in output of daemon. | |
| 63 | +| `unfocus` | Command to execute on unfocus event, command runs via bash and won't be killed on daemon exit, output is hidden for avoid mess in output of daemon. | |
| 64 | + |
| 65 | +#### Config path |
| 66 | +- Daemon searches for following configuration files by priority: |
| 67 | + - `/etc/flux.ini` |
| 68 | + - `$XDG_CONFIG_HOME/flux.ini` |
| 69 | + - `~/.config/flux.ini` |
| 70 | + |
| 71 | +#### Limitations |
| 72 | +Since INI is not standartized, I should mention all supported features here. |
| 73 | +- Supported: |
| 74 | + - Spaces in section names. |
| 75 | + - Single and double quoted strings. |
| 76 | + - Commented lines and inline comments using `;` and/or `#` symbols. |
| 77 | + - Сase insensitive name of keys. |
| 78 | + - Insensetivity to spaces before and after `=` symbol. |
| 79 | +- Unsupported: |
| 80 | + - Regular expressions. |
| 81 | + - Inline comment on lines with section name. |
| 82 | + - Line continuation using `\` symbol. |
| 83 | + - Anything else what unmentioned above. |
| 84 | + |
| 85 | +#### Configuration example |
| 86 | +```ini |
| 87 | +; Long example |
| 88 | +[Forza Horizon 4] |
| 89 | +name = ForzaHorizon4.e |
| 90 | +executable = |
| 91 | +owner = 1000 |
| 92 | +cpulimit = 40 |
| 93 | +delay = 1 |
| 94 | +focus = killall picom |
| 95 | +unfocus = picom |
| 96 | + |
| 97 | +; Short example |
| 98 | +[Geometry Dash] |
| 99 | +name = GeometryDash.ex |
| 100 | +cpulimit = 0 |
| 101 | +delay = 1 |
| 102 | + |
| 103 | +; Do not apply limits, execute commands on events instead |
| 104 | +[Mednafen] |
| 105 | +name = mednafen |
| 106 | +focus = killall picom |
| 107 | +unfocus = picom |
| 108 | +``` |
| 109 | + |
| 110 | +### Possible questions |
| 111 | +- Should I trust you and this utility? |
| 112 | + - You can read entire code. If you are uncomfortable, feel free to avoid using it. |
| 113 | +- Is it safe? |
| 114 | + - Yes, all daemon does is read events from X11 related to window focus. Neither I nor daemon has access to your data. |
| 115 | +- Can I get banned in a game because of this daemon? |
| 116 | + - Nowadays, anti-cheats are pure garbage, developed by freaks without balls, and you can get banned even for a wrong click. |
| 117 | +- Why was that daemon developed? |
| 118 | + - Main task is to reduce CPU usage of games that have been minimized. Almost every engine fails to recognize that game is unfocused and continues to consume a lot of CPU and GPU resources, what can make system slow for other tasks like browsing stuff, transcoding video etc. or even unresponsive at all. |
| 119 | +- Bugs? |
| 120 | + - Nothing is perfect in this world. Almost all bugs I encountered during development have been fixed. If you find a bug, open an issue. Known issues that cannot be fixed are: inability to interact with "glxgears" and "vkcube" windows, as they do not report their PIDs; freezing online games (setting 'cpulimit' to '0') causes disconnects from matches, so use lower CPU-limit to allow game to send/receive packets. |
| 121 | +- Why is code so complicated? |
| 122 | + - Long story short, try removing at least one line of code (that does not affect output, of course) and see what happens. That sounds easy - just apply a CPU-limit to a window when unfocused and remove it when focused, but it is a bit more complicated. Just check how much logic is used for that "easy" task. |
| 123 | +- Can I apply FPS-limits instead of CPU-limits? |
| 124 | + - No, at least not directly. You can use MangoHud with game, then add commands to 'focus' and 'unfocus' keys to modify 'fps_limit' option in MangoHud config on the fly using 'sed' tool. Since MangoHud reads config on fly, that works like a charm. |
| 125 | +- Gamescope exists, Wayland becomes more popular. Are you not late by any chance? |
| 126 | + - Well, not everyone is ready to switch to Wayland, there are a lot of reasons exists. Gamescope does not work well on my Nvidia desktop and Intel laptop, and I can bet it does not work well for others either. Also, there are a lot of old Nvidia GPUs that do not support Wayland at all because of old drivers, what makes Gamescope completely useless for owners of these GPUs. |
| 127 | +- What about Wayland support? |
| 128 | + - That is impossible, there is no any unified way to read window focus events and extract PIDs from windows on Wayland. |
0 commit comments