New feature: Niceness: change nice and ionice level of the local and/or remote process using the --nice option

[michaelmess-de]

Introduced new option --nice=... to specify the nice/ionice level for the local/remote process

rsync --nice (LOCATION|[LOCATION:]SETTING)[,...] ...

LOCATION: local|remote|all
    LOCAL is the local rsync process that has been started by the user/script/etc.
    REMOTE it the remote rsync process that has been started via SSH on the remote system
    ALL means both, local and remote.
    The constants are not case sensitive, thus e.g. REMOTE and remote are the same value.
    If omitted, the default is: all
SETTING: NICESETTING|IONICESETTING|NICESETTING/IONICESETTING
    If the whole setting is omitted, the default is 19/IDLE
NICESETTING:   -20...19
    Higher number means lower priority, negative numbers require root permissions
    If not specified in the setting, the default is 0. 
    No system call is made to set the priority 0.
    If the setting fails, e.g. due to the lack of permission to set negative nice
    priority, the issue is ignored and rsync will continue doing its work.
IONICESETTING: RT_0|RT_1|RT_2|RT_3|RT_4|RT_5|RT_6|RT_7|NONE|BE_0|BE_1|BE_2|BE_3|BE_4|BE_5|BE_6|BE_7|IDLE
    RT_X is realtime priority, need root permission
    BE_X is best effort with the given level
    IDLE means the process gets served only when no other processes are using disk io.
    NONE means best effort with level calculated by the formula (cpu_nice + 20) / 5
         and is the default that does not need to be set.
    The constants are not case sensitive, thus e.g. IDLE and idle are the same value.
    If not specified in the setting, the default is NONE.
    No system call is made to set the priority NONE.
    If the setting fails, e.g. due to the lack of permission to set realtime
    priority, the issue is ignored and rsync will continue doing its work.

Examples:

Specifying a setting for both, local and remote:
 --nice 19/idle = --nice all:19/idle
 --nice 19      = --nice all:19       (no ionice -> set 0)
 --nice idle    = --nice all:idle     (no nice -> set 0)
 --nice 0       = --nice all:0        (nice value 0 and no ionice -> 0/0 == unset)

Specifying a setting for the given location:
 -- nice local:19,remote:5
 -- nice local:19/idle,remote:5
 -- nice local:19/be_0,remote:idle

No setting specified means default 19/idle:
 -- nice local   = --nice local:19/idle
 -- nice remote  = --nice remote:19/idle
 -- nice all, -Q = --nice local,remote = --nice local --nice remote

Any specific setting set before may be overwritten by the following setting, e. g.:
 --nice local:5 --nice all 
 --nice local:6/idle,all
 --nice local:5 --nice remote:6 -Q
would result in setting the default 19/idle for both, local and remote.

nice and ionice are always set as a pair, even when only one of them is specified.
 --nice remote:5 --nice remote:idle
therefore would result in an unset nice value and ionice value idle beeing applied.

With this approach, all valid values for nice and ionice can be applied and successfully set, provided that any necessary permissions are available (root, CAP_SYS_NICE, CAP_SYS_ADMIN) for the affected process.
In case the priority cannot be set (Permission denied), rsync will just issue a warning and continue normally.

For keeping or lowering priority, that means nice values >= 0 and ionice values of NONE, BE_X, IDLE no special permissions are required.