RFC: documentation of the autogroup feature

From: Michael Kerrisk (man-pages)
Date: Tue Nov 22 2016 - 11:18:31 EST

Hello Mike and others,

The autogroup feature that you added in 2.6.38 remains poorly
documented, so I took a stab at adding some text to the sched(7)
manual page. There are still a few pieces to be fixed, and you
may also see some other pieces that should be added. Could I
ask you to take a look at the text below?



The autogroup feature
Since Linux 2.6.38, the kernel provides a feature known as
autogrouping to improve interactive desktop performance in the
face of multiprocess CPU-intensive workloads such as building
the Linux kernel with large numbers of parallel build processes
(i.e., the make(1) -j flag).

This feature operates in conjunction with the CFS scheduler and
requires a kernel that is configured with CONFIG_SCHED_AUTOâ
GROUP. On a running system, this feature is enabled or disâ
abled via the file /proc/sys/kernel/sched_autogroup_enabled; a
value of 0 disables the feature, while a value of 1 enables it.
The default value in this file is 1, unless the kernel was
booted with the noautogroup parameter.

When autogrouping is enabled, processes are automatically
placed into "task groups" for the purposes of scheduling. In
the current implementation, a new task group is created when a
new session is created via setsid(2), as happens, for example,
when a new terminal window is created. A task group is autoâ
matically destroyed when the last process in the group termiâ

âThe following is a little vague. Does it need to be â
âmade more precise? â
The CFS scheduler employs an algorithm that distributes the CPU
across task groups. As a result of this algorithm, the proâ
cesses in task groups that contain multiple CPU-intensive proâ
cesses are in effect disfavored by the scheduler.

A process's autogroup (task group) membership can be viewed via
the file /proc/[pid]/autogroup:

$ cat /proc/1/autogroup
/autogroup-1 nice 0

This file can also be used to modify the CPU bandwidth alloâ
cated to a task group. This is done by writing a number in the
"nice" range to the file to set the task group's nice value.
The allowed range is from +19 (low priority) to -20 (high priâ
ority). Note that all values in this range cause a task group
to be further disfavored by the scheduler, with -20 resulting
in the scheduler mildy disfavoring the task group and +19
greatly disfavoring it.

âRegarding the previous paragraph... My tests indiâ â
âcate that writing *any* value to the autogroup file â
âcauses the task group to get a lower priority. This â
âsomewhat surprised me, since I assumed (based on the â
âparallel with the process nice(2) value) that negaâ â
âtive values might boost the task group's priority â
âabove a task group whose autogroup file had not been â
âtouched. â
â â
âIs this the expected behavior? I presume it is... â
â â
âBut then there's a small surprise in the interface. â
âSuppose that the value 0 is written to the autogroup â
âfile, then this results in the task group being sigâ â
ânificantly disfavored. But, the nice value *shown* â
âin the autogroup file will be the same as if the â
âfile had not been modified. So, the user has no way â
âof discovering the difference. That seems odd. Am I â
âmissing something? â

âIs the following correct? Does the statement need to â
âbe more precise? (E.g., in precisely which circumâ â
âstances does the use of cgroups override autogroup?) â
The use of the cgroups(7) CPU controller overrides the effect
of autogrouping.

âWhat needs to be said about autogroup and real-time â
âtasks? â

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/