Re: [PATCH v2] clone.2: Document CLONE_INTO_CGROUP

[Michael Kerrisk (man-pages)]

On 5/19/20 3:51 PM, Christian Brauner wrote:
> On Tue, May 19, 2020 at 03:36:28PM +0200, Michael Kerrisk (man-pages) wrote:
>> On 5/18/20 7:55 PM, Christian Brauner wrote:
>>> From: Christian Brauner <christian.brauner@xxxxxxxxxx>
>>> +
>>> +Spawning a process into a cgroup different from the parent's cgroup
>>> +makes it possible for a service manager to directly spawn new
>>> +services into dedicated cgroups. This allows eliminating accounting
>>> +jitter which would be caused by the new process living in the
>>> +parent's cgroup for a short amount of time before being
>>> +moved into the target cgroup. This flag also allows the creation of
>>> +frozen child process by spawning them into a frozen cgroup (see
>>> +.BR cgroups (7)
>>> +for a description of the freezer feature in version 2 cgroups).
>>> +For threaded applications or even thread implementations which
>>> +make use of cgroups to limit individual threads it is possible to
>>> +establish a fixed cgroup layout before spawning each thread
>>> +directly into its target cgroup.
>>
>> Thanks for these use cases; that's great!
>>
>> So, I did some fairly heavy editing, which resulted in the
>> following (the sum of the diffs is shown at the end of this
>> mail):
>>
>>        CLONE_INTO_CGROUP (since Linux 5.7)
>>               By default, a child process is placed in the same version 2
>>               cgroup  as  its  parent.   The CLONE_INTO_CGROUP allows the
> 
> Not a native speaker, but is this missing a noun like "flag"?
> "The CLONE_INTO_CGROUP {flag,feature} allows the [...]"?

Yes, "flag" was missing. Thanks.

>>               child process to  be  created  in  a  different  version  2
>>               cgroup.   (Note  that CLONE_INTO_CGROUP has effect only for
>>               version 2 cgroups.)
>>
>>               In order to place the child process in a different  cgroup,
>>               the caller specifies CLONE_INTO_CGROUP in cl_args.flags and
>>               passes a file descriptor that refers to a version 2  cgroup
>>               in  the cl_args.cgroup field.  (This file descriptor can be
>>               obtained by opening a cgroup v2 directory file using either
> 
> Should this just be "opening a cgroup v2 directory" and not "directory
> file"? Feels redundant.

Yes, better. Changed.
 
>>               the  O_RDONLY  or  the  O_PATH flag.)  Note that all of the
>>               usual restrictions (described in cgroups(7)) on  placing  a
>>               process into a version 2 cgroup apply.
>>
>>               Spawning  a  process  into a cgroup different from the parâ
>>               ent's cgroup makes it possible for  a  service  manager  to
>>               directly  spawn  new services into dedicated cgroups.  This
>>               eliminates the accounting jitter that would  be  caused  if
>>               the  child  process was first created in the same cgroup as
>>               the parent and then moved  into  the  target  cgroup.   The
> 
> I forgot to mention that spawning directly into a target cgroup is also
> more efficient than moving it after creation. The specific reason is
> mentioned in the commit message, the write lock of the semaphore need
> not be taken in contrast to when it is moved afterwards. That
> implementation details is not that interesting but it might be
> interesting to know that it provides performance benefits in general.

Thanks. I added this sentence:

    Furthermore, spawning the child process directly into a 
    target cgroup is significantly cheaper than moving the child 
    process into the target cgroup after it has been created.

>> Look okay to you?
> 
> Yep, looks great!

Good!

Thanks for the review.

Cheers,

Michael


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