RFC: documentation of the autogroup feature

[Michael Kerrisk (man-pages)]

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?

Cheers,

Michael

   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â
       nates.



       âââââââââââââââââââââââââââââââââââââââââââââââââââââââ
       âFIXME                                                â
       âââââââââââââââââââââââââââââââââââââââââââââââââââââââ
       â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.


       âââââââââââââââââââââââââââââââââââââââââââââââââââââââ
       âFIXME                                                â
       âââââââââââââââââââââââââââââââââââââââââââââââââââââââ
       â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?                                   â
       âââââââââââââââââââââââââââââââââââââââââââââââââââââââ



       âââââââââââââââââââââââââââââââââââââââââââââââââââââââ
       âFIXME                                                â
       âââââââââââââââââââââââââââââââââââââââââââââââââââââââ
       â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.


       âââââââââââââââââââââââââââââââââââââââââââââââââââââââ
       âFIXME                                                â
       âââââââââââââââââââââââââââââââââââââââââââââââââââââââ
       â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/