xsuspender - auto-suspend inactive X11 applications
xsuspender
Modern desktop GUI applications may use up significant system resources, such as CPU time, just while idly running and even when unused. Respecting expressive configuration, XSuspender moderates such applications to suspend all activity shortly after their windows are unfocused. by sending them Unix signal SIGSTOP (or executing a custom script; see exec_suspend key in section CONFIGURATION below). When the application window regains focus, XSuspender sends it signal SIGCONT, and it resumes execution exactly where it had left off.
This may result in significant reduction in CPU use which prolongs battery run-time (5-500%; subject to user’s computing habits), reduces CPU fan noise, and prevents resource-hogging applications from plotting stuff behind your back at least when you are not actively using them.
The method also has its share of drawbacks. See section BUGS below.
The program is
mainly run without arguments.
-h, --help
Print short help and exit.
G_MESSAGES_DEBUG
Set G_MESSAGES_DEBUG=xsuspender to have the program report debug messages of its activity to standard error.
XDG_CONFIG_HOME
If set, the directory where xsuspender.conf configuration file can be found. If missing, this location defaults to ~/.config.
~/.config/xsuspender.conf
Configuration file read by the program.
$XDG_CONFIG_HOME/xsuspender.conf
Alternative configuration file when the variable is set.
share/doc/xsuspender/examples/xsuspender.conf
Example configuration file shipped with the program.
etc/xdg/autostart/xsuspender.desktop
A desktop session auto-start launcher. Disabled by default. To enable, copy it into ~/.config/autostart directory (or $XDG_CONFIG_HOME/autostart where applicable) and edit it, setting Hidden=false. Alternatively, you may be able to enable it via the session application auto-start manager.
Configuration key-value file is in INI format. Notice:
|
• |
file must be encoded in UTF-8, |
|||
|
• |
comments follow ’#’ character, |
|||
|
• |
section and key names are case-sensitive. |
The file should contain a [Default] section which all other sections inherit and override on per-key basis.
Each
non-[Default] section constitutes a rule that
XSuspender will try to match and follow. Sections can define
the following keys (listed with built-in default values, if
any):
match_wm_name_contains
match_wm_class_contains
match_wm_class_group_contains
These keys order xsuspender to apply the rule only to windows that contain the verbatim value string in their WM_NAME and WM_CLASS window manager hints. When multiple matching keys are specified, their logical conjunction (intersection) applies. To find applicable values, run:
xprop -notype WM_NAME WM_CLASS
and click on the window of interest. Class group is the second string in the WM_CLASS atom.
suspend_delay = 10
Integer seconds to wait after the window loses focus before suspending it. Setting a reasonable value avoids suspending processes too early during rapid task switching. If you set this value too low, upon process termination, the process may stall in its termination routine if it hasn’t been able to finish in time. Since we’re unable to detect this, best give your processes ample time.
resume_every = 50
Resume the suspended process every this many integer seconds to have it do (some of) its backlog of work.
resume_for = 5
Resume suspended process only for this long before suspending it again.
only_on_battery = true
Apply the rule only when on battery power. You may wish to set this to false for hopelessly annoying processes such as virtual machines running Windos.
auto_suspend_on_battery = true
If true, automatically apply this rule when switching to batter power, even if the matching window didn’t just lose focus (but lost it some time before).
suspend_subtree_pattern
Extended regular expression. If provided, when XSuspender suspends a process, it will also suspend all its descendant processes (children, grandchildren etc.) whose command-line string matches the pattern. Set to . to match and kill all descendants. This setting only applies when send_signals is also true.
exec_suspend
exec_resume
Before suspending / resuming the process, execute the string as a command-line shell script. If the script execution is successful (exit status 0), proceed with process suspension, otherwise abort it. (Process resumption is never aborted.)
The executed script gets passed via the environment the following variables: PID (process id), XID (X11 window id of the triggering window), and WM_NAME (window title).
You can use these keys to control suspension of your processes or disjoint components thereof in a custom way. In this case, you may also find send_signals key to be of use.
send_signals = true
If true, XSuspender kills the matching process with SIGSTOP / SIGCONT Unix signals. If false, XSuspender sends no signals of its own, deferring to custom exec_suspend and exec_resume scripts to do the work.
downclock_on_battery = 0
Set to greater than zero to decrease the CPU time allotted to the matching process when running on battery power. For every one time slice running, the process sleeps for this many slices. Thus, a value 1 decreases the CPU consumption of the process by 50%, a value of 2 by 66%, a value of N by N/(N+1)%, and so on. A value of 0 disables downclocking.
This is a separate, stand-alone mechanism that limits CPU consumption of, also and in particular, focused windows.
The following limitations and quirks are known:
|
• |
Don’t configure XSuspender for software you want to keep continuously alive in the background, such as music players and daemons. If you suspend IM clients, wake them up frequently (configuration key resume_every) so they can process their queued network events. If you like to stream music from YouTube or similar, you might want to exempt your browser from suspension, or consider using a lighter-weight native client, such as Musictube. | ||
|
• |
Windows that minimize to system tray, such as torrent and IM clients, need to be resumed frequently to respond to tray icon click events in a seamless manner. | ||
|
• |
Pasting from clipboard is prevented while the selection source process is suspended. Mitigate by using a clipboard manager that takes ownership of the selection. | ||
|
• |
Suspended windows might not redraw until regaining focus. If something covers them, expect visual artifacts. | ||
|
• |
Mouse-wheel scrolling might not work in suspended windows. They require keyboard input focus to resume. | ||
|
• |
Processes that take a long time to shut down after their window already disappears may be stopped in the middle of their termination routines. Avoid with a reasonably generous suspend_delay. | ||
|
• |
XSuspender won’t work in remote X sessions. | ||
|
• |
XSuspender won’t work with Wayland. |
Please raise any further bugs and ideas on the project’s GitHub issue tracker.
Example configuration section for VirtualBox:
# This is a comment.
[Default]
suspend_delay = 10
resume_every = 50
resume_for = 5
only_on_battery = true
auto_suspend_on_battery = true
send_signals = true
# Rule name is
an alphanumeric string.
# Rule VirtualBox inherits from Default rule
[VirtualBox]
match_wm_class_contains = VirtualBox
# VirtualBox
suspension is managed by VBoxManage utility.
send_signals = false
# We get the VM
UUID via its process command line.
# NOTE: Unlike in this example, the whole script should be
# on a single line.
exec_suspend = VBoxManage controlvm "$(ps -o args= -q
$PID | \
sed -E ’s/.*--startvm ([a-f0-9-]+).*/\1/’)"
pause
exec_resume = VBoxManage controlvm "$(ps -o args= -q
$PID | \
sed -E ’s/.*--startvm ([a-f0-9-]+).*/\1/’)"
resume
Find further examples in example configuration file accompanying this distribution (see section FILES above).
To debug your configuration rules, run:
G_MESSAGES_DEBUG=xsuspender xsuspender
kill(1), xprop(1), regex(7), signal(7)