Re: RFC: documentation of the autogroup feature

[Michael Kerrisk (man-pages)]

Hi Mike,

On 11/23/2016 04:33 PM, Mike Galbraith wrote:
> On Wed, 2016-11-23 at 14:54 +0100, Michael Kerrisk (man-pages) wrote:
>> Hi Mike,
>>
>> First off, I better say that I'm not at all intimate with the details
>> of the scheduler, so bear with me...
>>
>> On 11/23/2016 12:39 PM, Mike Galbraith wrote:
>>> On Tue, 2016-11-22 at 16:59 +0100, Michael Kerrisk (man-pages) wrote:
>>>
>>>>        ┌─────────────────────────────────────────────────────┐
>>>>        │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.
>>>
>>> Mmmm, they're actually equalized (modulo smp fairness goop), but I see
>>> what you mean.
>>
>> I couldn't quite grok that sentence. My problem is resolving "they".
>> Do you mean: "the CPU scheduler equalizes the distribution of
>> CPU cycles across task groups"?
> 
> Sort of.  "They" are scheduler entities, runqueue (group) or task.  The
> scheduler equalizes entity vruntimes.

Okay -- I'll see if I can come up with some wording there.

>  
>>>>        │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.
>>>
>>> Correct, autogroup defers to cgroups.  Perhaps mention that moving a
>>> task back to the root task group will result in the autogroup again
>>> taking effect.
>>
>> In what circumstances does a process get moved back to the root 
>> task group?
> 
> Userspace actions, tool or human fingers.

Could you say a little more please. What Kernel-user-space 
APIs/system calls/etc. cause this to happen?

>> Actually, can you define for me what the root task group is, and 
>> why it exists? That may be worth some words in this man page.
> 
> I don't think we need group scheduling details, there's plenty of
> documentation elsewhere for those who want theory.  

Well, you suggested above 

    Perhaps mention that moving a task back to the root task
    group will result in the autogroup again taking effect.

So, that inevitable would lead me and the reader of the man page
to ask: what's the root task group?

> Autogroup is for
> those who don't want to have to care (which is also why it should have
> never grown nice knob).

Yes, that I understand that much :-).

Cheers,

Michael


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