github/runwhenidle
1
1
Fork 0
mirror of https://github.com/perk11/runwhenidle.git synced 2026-01-10 06:08:00 -05:00
Code Issues Packages Projects Releases Wiki Activity

README.md improvements

Browse Source 
Restructure, improve examples and more
This commit is contained in:
Konstantin Pereiaslov
2024-01-07 09:50:32 +03:00
committed by GitHub
parent 5055d4f949
commit 86011052aa
1 changed files with 46 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
README.md
View File

@@ -1,22 +1,51 @@
# runwhenidle
runwhenidle is a Linux utility that can be used to run a computationally or IO-intensive program when user is not
in front of the computer, pausing it once the user is back, resuming once the user left, often without requiring
adaptation from the program being run.
runwhenidle is a Linux utility that can be used to pause a computationally or IO-intensive program when user is
in front of the computer, resuming it once the user is away, usually without requiring adaptation from the program
being run. It can run a command given to it or monitor an already running command.
runwhenidle runs a command given to it or monitors an existing command with `--pid` parameter, pauses it if the user
is active by sending SIGSTOP (or optionally SIGTSTP) to the command and all its child processes.
When the user activity stops, runwhenidle resumes the command by sending it and all the child processes SIGCONT signal.
It then checks once per second if user activity has resumed, and once it is, pauses the command and its child processes again.
## Example 1:
runwhenidle uses XScreenSaverQueryInfo() to check when last user activity happened therefore a running X server is
required.
Wayland is not currently supported.
The simplest way to start using runwhenidle is just by putting it in front of the command:
runwhenidle rsync -rva /home /backup
## Example 2:
runwhenidle --start-monitor-after=10 --timeout=30 --quiet ffmpeg -i file.mp4 file.mkv
In this example `ffmpeg` will run for 10 seconds uninterrupted. After 10 seconds pass,
runwhenidle will start monitoring user activity and pause ffmpeg if user has been active within last 30 seconds.
If user is inactive for 30 seconds, resume the operation of ffmpeg. `--quiet` option makes sure runwhenidle doesn't
output anything other than the output of `ffmpeg`. Same command can be ran with the short versions of the arguments:
runwhenidle -a 10 -t 30 -q ffmpeg -i file.mp4 file.mkv
## Example 3:
runwhenidle --pid=12345 --pause-method=SIGTSTP --verbose
Start monitoring user activity and when user is active, pause process with PID 12345. Unpause it when user is inactive
for 300 seconds. Use SIGTSTP which the process 12345 can handle or ignore instead of the default SIGSTOP that is
always handled by the OS.
## Under the Hood: How runwhenidle Controls Processes Based on User Activity
runwhenidle uses XScreenSaverQueryInfo() to check when last user activity happened.
Therefore, running X server is required. Wayland is not currently supported.
When user is active, these checks happen as infrequently as possible to satisfy the desired inactivity timeout
(default - every 5 minutes). When user is inactive, these checks happen once per second, to allow to restore
the system responsiveness quickly.
When runwhenidle determines that the user is active, it will send SIGSTOP (or optionally SIGTSTP) to the command
and all its child processes. When the user activity stops, runwhenidle resumes the command by sending it and all
the child processes SIGCONT signal. It then checks once per second if user activity has resumed, and once it is,
pauses the command and its child processes again.
If runwhenidle was used to start a command (i.e. `--pid` parameter was not used) and it receives an interruption
signal (SIGINT or SIGTERM), it will pass that signal to the command it is
running, resume the command if it previously paused it, stop checking for user activity and will wait for the command
to handle the signal.
signal (SIGINT or SIGTERM), it will pass that signal to the command it is running, resume the command if it
previously paused it, stop checking for user activity and will wait for the command to handle the signal.
## Installation
@@ -38,33 +67,11 @@ If you want to install it system-wide, run `sudo make install` or simply `sudo c
runwhenidle [OPTIONS] [shell_command_to_run] [shell_command_arguments]
### Example 1:
runwhenidle -t 100 -v rsync /filea /fileb
Run the `rsync` command and pause it while user is active. When user is inactive for 100 seconds, resume the command.
Output debug information to stderr.
### Example 2:
runwhenidle --start-monitor-after=10 --timeout=30 --quiet ffmpeg -i file.mp4 file.mkv
Run the `ffmpeg` for 10 seconds uninterrupted. After 10 seconds pass, start monitoring user activity and pause ffmpeg
if user has been active within last 30 seconds. If user is inactive for 30 seconds, resume the operation of ffmpeg.
`--quiet` option makes sure runwhenidle doesn't output anything other than the output of `ffmpeg`.
### Example 3:
runwhenidle -p 12345
Start monitoring user activity and when user is active, pause process with PID 12345, unpause it when user is inactive
for 300 seconds.
### All options
### Options
| Option | Description | Default Value |
|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
| `--timeout\| -t <seconds>` | Set the user idle time after which the command can run in seconds. | 300 seconds |
| `--timeout\| -t <seconds>` | Set the user idle time after which the command can be resumed in seconds. | 300 seconds |
| `--pid\|-p <pid>` | Monitor an existing command rather than start a new one. When this option is used, shell_command_to_run should not be passed. | |
| `--start-monitor-after\| -a <ms>` | Set an initial delay in milliseconds before monitoring starts. During this time command runs unrestricted. This helps to catch quick errors. | 300 ms |
| `--pause-method\| -m <method>` | Specify method for pausing the command when the user is not idle. Available Options: SIGTSTP (can be ignored by the program), SIGSTOP (cannot be ignored). | SIGSTOP |
@@ -78,6 +85,8 @@ for 300 seconds.
1. Wayland support. runwhenidle currently doesn't work without XScreenSaver, but Wayland support should be possible and
is planned (at least for the DEs supporting ext-idle-notify, which now both Gnome and KDE support).
2. When monitoring an existing pid, once it gets paused, it gets detached from the terminal it was in.
Running "fg" command could be a workaround to get it reattached, but it is required after every pause.
### Building Ubuntu/Debian package