2-1 まで 4.3 カーネルの文書と同期。

Cgroup unified hierarchy

April, 2014		Tejun Heo <tj@kernel.org>

This document describes the changes made by unified hierarchy and
their rationales.  It will eventually be merged into the main cgroup
documentation.

この文書は単一階層構造によって起こる変化とその原理について説明する．こ
の文書は最終的にはメインの cgroup の文書にマージされる予定である．

CONTENTS

1. Background
2. Basic Operation
  2-1. Mounting
  2-2. cgroup.subtree_control
  2-3. cgroup.controllers
3. Structural Constraints
  3-1. Top-down
  3-2. No internal tasks
4. Delegation
  4-1. Model of delegation
  4-2. Common ancestor rule
5. Other Changes
  5-1. [Un]populated Notification
  5-2. Other Core Changes
  5-3. Controller File Conventions
    5-3-1. Format
    5-3-2. Control Knobs
  5-4. Per-Controller Changes
    5-4-1. io
    5-4-2. cpuset
    5-4-3. memory
6. Planned Changes
  6-1. CAP for resource control


1. Background

cgroup allows arbitrary number of hierarchies and each hierarchy can
host any number of controllers.  While this seems to provide high
level of flexibility, it isn't quite useful in practice.

cgroup は任意の数の階層構造を作成可能で，それぞれがいくつもの数のコン
トローラをホスト可能である．これは高度な柔軟性を提供するように見えるが，
実際は役に立たない．

For example, as there is only one instance of each controller, utility
type controllers such as freezer which can be useful in all
hierarchies can only be used in one.  The issue is exacerbated by the
fact that controllers can't be moved around once hierarchies are
populated.  Another issue is that all controllers bound to a hierarchy
are forced to have exactly the same view of the hierarchy.  It isn't
possible to vary the granularity depending on the specific controller.

例えば，コントローラごとに一つのインスタンスのみあるような場合，全ての
階層構造に役に立つ freezer のようなユーティリティタイプのコントローラ
が 1 つでしか使えない．この問題は，一度階層が構築されると，コントロー
ラはあちこち移動することができないという事実によって悪化する．他に，階
層に結びついた全てのコントローラは，全く同じビューの階層をを持つことを
強制されているという問題がある．特定のコントローラに依存するような粒度
に変化することができない．

In practice, these issues heavily limit which controllers can be put
on the same hierarchy and most configurations resort to putting each
controller on its own hierarchy.  Only closely related ones, such as
cpu and cpuacct, make sense to put on the same hierarchy.  This often
means that userland ends up managing multiple similar hierarchies
repeating the same steps on each hierarchy whenever a hierarchy
management operation is necessary.

実際，これらの問題は同じ階層にコントローラを置く事を大きく制限しており，
ほとんどの構成では，各コントローラが自身の階層を持つ構成を用いている．
cpu と cpuacct のように密接に関係したコントローラだけが，同じ階層に置
く意味がある．これにより，ユーザランドでは，階層に対する操作が必要な時
は常に，同じような階層に対して，それぞれの階層に同じような操作を繰り返
すことになっている．

Unfortunately, support for multiple hierarchies comes at a steep cost.
Internal implementation in cgroup core proper is dazzlingly
complicated but more importantly the support for multiple hierarchies
restricts how cgroup is used in general and what controllers can do.

残念ながら、複数階層構造のサポートは法外なコストがかかる。適切な
cgroup コアの内部実装は目もくらむほど複雑であるが、より重要なのは、複
数階層構造のサポートは、一般的な cgroup の使い方やコントローラができる
ことをも制限してしまうことである。

There's no limit on how many hierarchies there may be, which means
that a task's cgroup membership can't be described in finite length.
The key may contain any varying number of entries and is unlimited in
length, which makes it highly awkward to handle and leads to addition
of controllers which exist only to identify membership, which in turn
exacerbates the original problem.

階層構造の数に制限がない事は、タスクが cgroup のメンバーであることが有限の
長さで記述できないということである。このキーポイントは、エントリ数が任
意に変化することと、長さが無制限になる事を含む。このことは、扱いが非常
に複雑になり、メンバーシップの確認のためだけに存在するコントローラの追
加につながる。この問題は巡り巡って元の問題を悪化させる。

Also, as a controller can't have any expectation regarding what shape
of hierarchies other controllers would be on, each controller has to
assume that all other controllers are operating on completely
orthogonal hierarchies.  This makes it impossible, or at least very
cumbersome, for controllers to cooperate with each other.

加えて、コントローラは他のコントローラがどのような階層の形状になるのか
に関しての予測ができないので、他のコントローラがそれぞれ完全に直交する
階層の上で操作されることを仮定しなければならない。コントローラがお互い
に協調して動作するには、これは不可能であるか、少なくとも非常に負荷が大
きくなる。

In most use cases, putting controllers on hierarchies which are
completely orthogonal to each other isn't necessary.  What usually is
called for is the ability to have differing levels of granularity
depending on the specific controller.  IOW, hierarchy may be collapsed
from leaf towards root when viewed from specific controllers.  For
example, a given configuration might not care about how memory is
distributed beyond certain level while still want to control how cpu
cycles are distributed.

ユースケースのほとんどでは、お互い完全に直交している階層構造にコントロー
ラを置く必要はない。通常求められているものは、特定のコントローラに依存
する異なる粒度のレベルを持つ能力である。言い換えると、階層は特定のコン
トローラの視点から見た時、末端からルートに向かって崩壊していくかもしれ
ないということである。例えば、与えられた設定では、あるレベルを超えてメ
モリを配分するかについては設定されないかもしれないが、CPU サイクルの分
配はコントロールしたいかもしれないというような事である。

Unified hierarchy is the next version of cgroup interface.  It aims to
address the aforementioned issues by having more structure while
retaining enough flexibility for most use cases.  Various other
general and controller-specific interface issues are also addressed in
the process.

単一階層構造は cgroup インターフェースの次のバージョンとなる。これは、
ほとんどのユースケースにおいて十分な柔軟性を確保しながら、前述の問題に
取り組むためのものである。

2. Basic Operation

2-1. Mounting

Currently, unified hierarchy can be mounted with the following mount
command.  Note that this is still under development and scheduled to
change soon.

現時点では、単一階層構造は以下のようなマウントコマンドでマウント可能で
ある。これはまだ開発中で、すぐに変更される予定であることに注意すること。

 mount -t cgroup -o __DEVEL__sane_behavior cgroup $MOUNT_POINT

All controllers which support the unified hierarchy and are not bound
to other hierarchies are automatically bound to unified hierarchy and
show up at the root of it.  Controllers which are enabled only in the
root of unified hierarchy can be bound to other hierarchies.  This
allows mixing unified hierarchy with the traditional multiple
hierarchies in a fully backward compatible way.

単一階層構造をサポートしており、他の階層にバインドされない全てのコント
ローラが、自動的に単一階層構造にバインドされ、そのルートに出現する。単
一階層のルート内でだけ有効なコントローラは、他の階層構造にバインドする
ことが可能である。これにより、単一階層構造と従来の複数階層構造を後方互
換性のために同居可能となる。

For development purposes, the following boot parameter makes all
controllers to appear on the unified hierarchy whether supported or
not.

開発目的で、以下のブートパラメータを指定すると、単一階層構造をサポート
している・いないに関わらず、全てのコントローラが単一階層構造下に現れる。

 cgroup__DEVEL__legacy_files_on_dfl

A controller can be moved across hierarchies only after the controller
is no longer referenced in its current hierarchy.  Because per-cgroup
controller states are destroyed asynchronously and controllers may
have lingering references, a controller may not show up immediately on
the unified hierarchy after the final umount of the previous
hierarchy.  Similarly, a controller should be fully disabled to be
moved out of the unified hierarchy and it may take some time for the
disabled controller to become available for other hierarchies;
furthermore, due to dependencies among controllers, other controllers
may need to be disabled too.

コントローラは、現在の階層内で参照されていない場合のみ、階層をまたいで
移動することができる。cgroup ごとのコントローラの状態は非同期で破壊さ
れ、参照が残ったままになる可能性があるので、前にマウントされていた階層
からアンマウントされたあとも、コントローラは単一階層構造にすぐに現れな
いかもしれない。同様に、コントローラが単一階層構造から出て行くには、完
全に無効化する必要がある。そして、無効化されたコントローラが他の階層で
利用可能になるには少し時間がかかるかもしれない。さらに、コントローラ間
の依存関係のために、他のコントローラも無効化する必要があるかもしれない。

While useful for development and manual configurations, dynamically
moving controllers between the unified and other hierarchies is
strongly discouraged for production use.  It is recommended to decide
the hierarchies and controller associations before starting using the
controllers.

開発と手動での設定には役に立つ一方で、単一階層構造と他の階層間でコント
ローラをダイナミックに移動することは、プロダクション利用では全く推奨さ
れない。

2-2. cgroup.subtree_control

All cgroups on unified hierarchy have "cgroup.subtree_control" file
which governs which controllers are enabled on the children of the
cgroup. Let's assume a hierarchy like the following.

単一階層上の全ての cgroup は cgroup.subtree_control ファイルを持つ。こ
れは、どのコントローラが cgroup の子供で有効になるのかを管理する。以下
のような階層を仮定しよう。

  root - A - B - C
               \ D

root's "cgroup.subtree_control" file determines which controllers are
enabled on A.  A's on B.  B's on C and D.  This coincides with the
fact that controllers on the immediate sub-level are used to
distribute the resources of the parent.  In fact, it's natural to
assume that resource control knobs of a child belong to its parent.
Enabling a controller in a "cgroup.subtree_control" file declares that
distribution of the respective resources of the cgroup will be
controlled.  Note that this means that controller enable states are
shared among siblings.

root の "cgroup.subtree_control" はどのコントローラが A で有効かを定義
する。A 上のものは B のを、B のものは C, D を定義する。これは、直近の
サブレベル上のコントローラは、親のリソースを分配するのに使われるという
事実に一致する。実際、親に属する子供のリソースコントロールノブを仮定す
るには自然である。"cgroup.subtree_control" でコントローラが有効化され
ると、それぞれの cgroup のリソースの配分を制御することを宣言することに
なる。コントローラの有効化の状態は兄弟間で共有されることを意味すること
に注意が必要である。

When read, the file contains space-separated list of currently enabled
controllers.  A write to the file should contain spaced-separated list
of controllers with '+' or '-' prefixed (without the quotes).
Controllers prefixed with '+' are enabled and '-' disabled.  If a
controller is listed multiple times, the last entry wins.  The
specific operations are executed atomically - either all succeed or
fail.

このファイルを読むと、現在有効なコントローラのスペース区切りのリストが
含まれる。ファイルへの書き込みは、コントローラの前に '+' か '-' をつけ
たスペース区切りのリストである必要がある (quote は不要)。'+' をつけた
コントローラは有効化され、'-' を付けたコントローラは無効化される。複数
回リストされているコントローラは最後の定義が有効になる。この指定のオペ
レーションはアトミックに実行される。つまり全て成功するか、全て失敗する
かである。

2-3. cgroup.controllers

Read-only "cgroup.controllers" contains space-separated list of
controllers which can be enabled in the cgroup's
"cgroup.subtree_control".

読み取り専用の "cgroup.controllers" はスペース区切りのコントローラのリ
ストが記載されている。このリストは "cgroup.subtree_control" で有効にす
ることのできるコントローラの一覧である。

In the root cgroup, this lists controllers which are not bound to
other hierarchies and the content changes as controllers are bound to
and unbound from other hierarchies.

ルート cgroup では、これは他の階層にバインドされていないコントローラの
リストとなる。また、ファイルの内容はコントローラが他の階層にバインドさ
れたりバインドを解除されたりすると変化する。

In non-root cgroups, the content of this file equals that of the
parent's "cgroup.subtree_control" as only controllers enabled from the
parent can be used in its children.

ルートでない cgroup では、このファイルの内容は親の
"cgroup.subtree_control" の内容に等しい。親で有効になったコントローラ
だけが子供内で使用できるからである。

3. Structural Constraints

3-1. Top-down

As it doesn't make sense to nest control of an uncontrolled resource,
all non-root "cgroup.subtree_control" can only contain controllers
which are enabled in the parent's "cgroup.subtree_control".  A
controller can be enabled only if the parent has the controller
enabled and a controller can't be disabled if one or more children
have it enabled.

コントロールできないリソースのネストされたコントロールに意味がないよう
に、全てのルート以外の "cgroup.subtree_control" は、親の
"cgroup.subtree_control" で有効になったコントローラだけを含む。コント
ローラは親で有効化されている時だけ有効にでき、有効にしている子供がいる
場合は無効化できない。

3-2. No internal tasks

One long-standing issue that cgroup faces is the competition between
tasks belonging to the parent cgroup and its children cgroups.  This
is inherently nasty as two different types of entities compete and
there is no agreed-upon obvious way to handle it.  Different
controllers are doing different things.

cgroup が直面している長年の課題は、親の cgroup に属するタスクと、その
子供に属するタスク間の競合である。これは2つの異なるタイプのエンティティ
の競合であり本質的に扱いにくい。これを扱う明確な同意された方法はない。
異なるコントローラは異なることを行っている。

The cpu controller considers tasks and cgroups as equivalents and maps
nice levels to cgroup weights. This works for some cases but falls flat when
children should be allocated specific ratios of cpu cycles and the
number of internal tasks fluctuates - the ratios constantly change as
the number of competing entities fluctuates.  There also are other
issues.  The mapping from nice level to weight isn't obvious or
universal, and there are various other knobs which simply aren't
available for tasks.

cpu コントローラはタスクと cgroup を等価なものとみなし、nice レベルを
cgroup のウェイトとマップする。これが有効なケースもあるが、子供に特定
の割合で CPU サイクルを割り当てる必要があるとき、そして内部タスクの数
が変動するとき、つまり競合するエンティティの数が変動して、割合が変化す
るときに破綻する。他の問題も存在する。nice レベルのウェイトへのマッピ
ングは明確で共通の方法が存在するわけではない。単純にタスクに利用できな
い他の様々なノブが存在する。

The io controller implicitly creates a hidden leaf node for each
cgroup to host the tasks.  The hidden leaf has its own copies of all
the knobs with "leaf_" prefixed.  While this allows equivalent control
over internal tasks, it's with serious drawbacks.  It always adds an
extra layer of nesting which may not be necessary, makes the interface
messy and significantly complicates the implementation.

io コントローラはタスクを扱うために暗黙にそれぞれの cgroup にリーフノー
ドを作成する。この隠れたリーフは自身のコピーとして、頭に "leaf_" と付
いた全てのノブを持つ。これは同等のコントロールが内部タスクにも可能にな
るが、重大な欠点も持つ。常に必要ではないかもしれないネストした余分なレ
イヤーを追加し、インターフェースを乱雑にして、実装をかなり複雑にする。

The memory controller currently doesn't have a way to control what
happens between internal tasks and child cgroups and the behavior is
not clearly defined.  There have been attempts to add ad-hoc behaviors
and knobs to tailor the behavior to specific workloads.  Continuing
this direction will lead to problems which will be extremely difficult
to resolve in the long term.

メモリコントローラは現時点では内部タスクと子cgroup間で起こっていること
をコントロールする方法はない。そして、振る舞いが明確には定義されていな
い。特定の作業に振る舞いを合わせるためのアドホックな振る舞いとノブが追
加されてきた。この方向性を続けることは長期間に渡って解決が非常に難しい
問題を引き起こすだろう。

Multiple controllers struggle with internal tasks and came up with
different ways to deal with it; unfortunately, all the approaches in
use now are severely flawed and, furthermore, the widely different
behaviors make cgroup as whole highly inconsistent.

複数のコントローラが内部タスクと奮闘しており、それを解決する色々な方法
を考えだしてきた。不幸にも、現在使用中の全てのアプローチは重大な欠点が
ある。その上、非常に異なった振る舞いが cgroup 全体を完全に一貫性のない
ものにしている。

It is clear that this is something which needs to be addressed from
cgroup core proper in a uniform way so that controllers don't need to
worry about it and cgroup as a whole shows a consistent and logical
behavior.  To achieve that, unified hierarchy enforces the following
structural constraint.

コントローラがそれについて心配する必要がないように、cgroup が全体とし
て一貫性とロジカルな振る舞いを示すように均一的な方法で cgroup core の
適正化に取り組む必要があるのは明らかある。これを達成するため、単一階層
構造では、以下の構造的な制約を強制する。

 Except for the root, only cgroups which don't contain any task may
 have controllers enabled in "cgroup.subtree_control".

 root を除いて、タスクを持たない cgroup だけが
 "cgroup.subtree_control" で有効になっているコントローラを持つことができる。

Combined with other properties, this guarantees that, when a
controller is looking at the part of the hierarchy which has it
enabled, tasks are always only on the leaves.  This rules out
situations where child cgroups compete against internal tasks of the
parent.

他のプロパティとくみあわせることで、この制約は、コントローラが有効にさ
れている階層の一部を見ているときは、常にタスクは葉ノードにのみ存在する
ことを保証します。これで、子 cgroup は親の内部タスクと競合するシチュエー
ションから逃れられます。

There are two things to note.  Firstly, the root cgroup is exempt from
the restriction.  Root contains tasks and anonymous resource
consumption which can't be associated with any other cgroup and
requires special treatment from most controllers.  How resource
consumption in the root cgroup is governed is upto each controller.

注意すべき点が2つある。root cgroup は制約を免除される。root は、
他の cgroup に関連付けることができないタスクやリソース消費を含んでおり、
ほとんどのコントローラから特別な扱いが必要である。root cgroup 内でどの
ようにしてリソース消費を管理するかは、それぞれのコントローラ次第である。

Secondly, the restriction doesn't take effect if there is no enabled
controller in the cgroup's "cgroup.subtree_control".  This is
important as otherwise it wouldn't be possible to create children of a
populated cgroup.  To control resource distribution of a cgroup, the
cgroup must create children and transfer all its tasks to the children
before enabling controllers in its "cgroup.subtree_control".

2つ目は、cgroup の "cgroup.subtree_control" で有効にされているコントロー
ラがない場合は、制約は効かないことである。でないとタスクが存在する
cgroup の子供を作れないので重要なことである。cgroup のリソース配分をコ
ントロールするために、cgroup は子を作らなければならない。そして
"cgroup.subtree_control" でコントローラを有効にする前に、そのタスクの
全てを子に移動させなければならない。

4. Delegation

4-1. Model of delegation

A cgroup can be delegated to a less privileged user by granting write
access of the directory and its "cgroup.procs" file to the user.  Note
that the resource control knobs in a given directory concern the
resources of the parent and thus must not be delegated along with the
directory.

cgroup は非特権ユーザに権限委譲できる。それはディレクトリと、
"cgroup.procs" ファイルへの書き込み権限を与えることにより可能である。
与えたディレクトリ内のリソースコントロールノブは、親のリソースに関係す
るので、ディレクトリと一緒に権限委譲してはいけないことに注意が必要である。

Once delegated, the user can build sub-hierarchy under the directory,
organize processes as it sees fit and further distribute the resources
it got from the parent.  The limits and other settings of all resource
controllers are hierarchical and regardless of what happens in the
delegated sub-hierarchy, nothing can escape the resource restrictions
imposed by the parent.

一度権限委譲すると、そのユーザはディレクトリ以下にサブ階層を構築できる。
そして、適切であると考えるようにプロセスを構造化でき、さらに親からもらっ
たリソースを分配できてしまう。全てのリソースコントローラの制限と他の設
定は階層的であり、移譲されたサブ階層で何が起ころうとも、いかなるものも
親によって課されたリソース制限から逃れられない。

Currently, cgroup doesn't impose any restrictions on the number of
cgroups in or nesting depth of a delegated sub-hierarchy; however,
this may in the future be limited explicitly.

現時点では、cgroup は cgroup の数、移譲されたサブ階層のネストの深さに
ついては何も制限されていない。しかし、将来は明確に制限されるかもしれない。

4-2. Common ancestor rule

On the unified hierarchy, to write to a "cgroup.procs" file, in
addition to the usual write permission to the file and uid match, the
writer must also have write access to the "cgroup.procs" file of the
common ancestor of the source and destination cgroups.  This prevents
delegatees from smuggling processes across disjoint sub-hierarchies.

単一階層構造では、"cgroup.procs" ファイルに書き込むために、ファイルへ
の通常の書き込み権と uid マッチに加えて、ライターはソースおよびデスティ
ネーションの共通の先祖の "cgroup.procs" への書き込み権も必要です。

Let's say cgroups C0 and C1 have been delegated to user U0 who created
C00, C01 under C0 and C10 under C1 as follows.

例えば以下のように、cgroup C0 と C1 は、C0 配下に C00, C01、C1 以下に
C10 を作ったユーザ U0 に権威移譲されているとしましょう。

 ~~~~~~~~~~~~~ - C0 - C00
 ~ cgroup    ~      \ C01
 ~ hierarchy ~
 ~~~~~~~~~~~~~ - C1 - C10

C0 and C1 are separate entities in terms of resource distribution
regardless of their relative positions in the hierarchy.  The
resources the processes under C0 are entitled to are controlled by
C0's ancestors and may be completely different from C1.  It's clear
that the intention of delegating C0 to U0 is allowing U0 to organize
the processes under C0 and further control the distribution of C0's
resources.

C0 と C1 は、階層内の相対的な位置に関わらず、リソース配分の観点から独
立したエンティティです。C0 以下のプロセスが与えられる権利があるリソー
スは、C0 の祖先にコントロールされ、おそらく C1 とは全く異なります。
U0 に対して C0 の権限を与えることは、U0 に C0 以下のプロセスを扱う許可
を与えることです。さらに C0 のリソースの分配をコントロールする許可も与
えます。

On traditional hierarchies, if a task has write access to "tasks" or
"cgroup.procs" file of a cgroup and its uid agrees with the target, it
can move the target to the cgroup.  In the above example, U0 will not
only be able to move processes in each sub-hierarchy but also across
the two sub-hierarchies, effectively allowing it to violate the
organizational and resource restrictions implied by the hierarchical
structure above C0 and C1.

これまでの階層構造では、タスクが cgroup の "tasks" もしくは
"cgroup.procs" ファイルへの書き込み権を持っていて、uid がターゲットに
一致しているなら、ターゲットを cgroup に移動できます。先の例でいうと、
U0 は各サブ階層内にプロセスを移動できるだけでなく、ふたつのサブ階層に
わたってもプロセスを移動できます。実際は、C0 と C1 より上の階層構造で
示されるリソース制限や構造を破ることができるようになるでしょう。

On the unified hierarchy, let's say U0 wants to write the pid of a
process which has a matching uid and is currently in C10 into
"C00/cgroup.procs".  U0 obviously has write access to the file and
migration permission on the process; however, the common ancestor of
the source cgroup C10 and the destination cgroup C00 is above the
points of delegation and U0 would not have write access to its
"cgroup.procs" and thus be denied with -EACCES.

これまでの階層構造では、タスクが cgroup の "tasks" もしくは
"cgroup.procs" ファイルへの書き込み権を持っていて、uid がターゲットに
一致しているなら、ターゲットを cgroup に移動できます。先の例でいうと、
U0 は各サブ階層内にプロセスを移動できるだけでなく、ふたつのサブ階層に
わたってもプロセスを移動できます。実際は、C0 と C1 より上の階層構造で
示されるリソース制限や構造を破ることができるようになるでしょう。


5. Other Changes

5-1. [Un]populated Notification

cgroup users often need a way to determine when a cgroup's
subhierarchy becomes empty so that it can be cleaned up.  cgroup
currently provides release_agent for it; unfortunately, this mechanism
is riddled with issues.

cgroup ユーザはよく cgroup のサブの階層が空になった際にクリーンアップ
できるように決定する方法が必要になることがある。cgroup は現在、この用
途のために release_agent を提供している。不幸なことに、このメカニズム
は問題に満ちあふれている。

- It delivers events by forking and execing a userland binary
  specified as the release_agent.  This is a long deprecated method of
  notification delivery.  It's extremely heavy, slow and cumbersome to
  integrate with larger infrastructure.
  
- これは release_agent で指定されたユーザランドのバイナリを fork して
  実行することでイベントを伝える。これは長く廃止予定となっている通知配
  信の方法である。大きなインフラで integrate するのが、極めて重く、遅
  い。

- There is single monitoring point at the root.  There's no way to
  delegate management of subtree.

- root に単一モニタリングポイントが存在する。サブツリーの管理を委任す
  る方法がない。

- The event isn't recursive.  It triggers when a cgroup doesn't have
  any tasks or child cgroups.  Events for internal nodes trigger only
  after all children are removed.  This again makes it impossible to
  delegate management of subtree.

- イベントは再帰的ではない。cgroup がタスクや子 cgroup を持っていない
  時にトリガする。内部ノードのイベントは、全ての子が削除された後にだけ
  トリガする。これも、サブツリーの管理の委任を不可能にする。

- Events are filtered from the kernel side.  "notify_on_release" file
  is used to subscribe to or suppress release event.  This is
  unnecessarily complicated and probably done this way because event
  delivery itself was expensive.

- イベントはカーネル側からフィルタされる。"notify_on_release" ファイル
  がリリースイベントを購読したり、やめたりするのに使われる。これは不必
  要に複雑であり、イベント配信自体が高価なのでおそらくこの方法で行われ
  る。

Unified hierarchy implements interface file "cgroup.subtree_populated"
which can be used to monitor whether the cgroup's subhierarchy has
tasks in it or not.  Its value is 0 if there is no task in the cgroup
and its descendants; otherwise, 1.  poll and [id]notify events are
triggered when the value changes.

単一階層構造はインターフェースとして "cgroup.subtree_populated" ファイ
ルを実装する。これは cgroup のサブ階層がタスクを持っているかいないかを
モニタするのに使われる。cgroup と子孫内にタスクがなければその値は 0 と
なる。そうでなければ 1 となる。この値が変わった場合、poll と
[id]notify イベントがトリガされる。

This is significantly lighter and simpler and trivially allows
delegating management of subhierarchy - subhierarchy monitoring can
block further propagation simply by putting itself or another process
in the root of the subhierarchy and monitor events that it's
interested in from there without interfering with monitoring higher in
the tree.

これは大幅に軽く、シンプルで、サブ階層の管理を委任できるのは明らかであ
る。サブ階層のモニタは、自身もしくは他のプロセスをサブ階層のルートに置
くことだけで更なる伝播をブロックできる。また、対象のモニタイベントをツ
リーの上位のモニタリングを妨げることなく、そこから監視できる。

In unified hierarchy, release_agent mechanism is no longer supported
and the interface files "release_agent" and "notify_on_release" do not
exist.

単一階層内では、release_agent メカニズムはもはやサポートされない。
"release_agent" インターフェースファイルと "notify_on_release" インター
フェースファイルも存在しない。

5-2. Other Core Changes

- None of the mount options is allowed.

- マウントオプションなしでも良くなる

- remount is disallowed.

- 再マウントは許可されない

- rename(2) is disallowed.

- rename(2) は許可されない

- "tasks" is removed.  Everything should at process granularity.  Use
  "cgroup.procs" instead.

- "tasks" は消去される。全てはプロセスの粒度でなされるべき。
  "cgroup.procs" が代わりに使われる。

- "cgroup.procs" is not sorted.  pids will be unique unless they got
  recycled in-between reads.

- "cgroup.procs" はソートされない。pid は、読み込み中にリサイクルされ
  た場合を除いてユニークである。

- "cgroup.clone_children" is removed.

- "cgroup.clojne_children" は消去される。

5-3. Controller File Conventions

5-3-1. Format

In general, all controller files should be in one of the following
formats whenever possible.

可能な場合はつねに、全てのコントローラファイルは以下のうちのひとつであ
る必要があります。

- Values only files
  値のみのファイル

  VAL0 VAL1...\n

- Flat keyed files
  フラットなキーのファイル

  KEY0 VAL0\n
  KEY1 VAL1\n
  ...

- Nested keyed files
  ネストしたキーのファイル

  KEY0 SUB_KEY0=VAL00 SUB_KEY1=VAL01...
  KEY1 SUB_KEY0=VAL10 SUB_KEY1=VAL11...
  ...

For a writeable file, the format for writing should generally match
reading; however, controllers may allow omitting later fields or
implement restricted shortcuts for most common use cases.

書き込み可能なファイルの場合は、書き込みのフォーマットは通常は読み取り
のときとマッチしている必要がある。しかし、コントローラは後のフィールド
を省略できるかもしれない。もしくは、最も一般的なユースケースのための制
限されたショートカットを実装できるかもしれない。

For both flat and nested keyed files, only the values for a single key
can be written at a time.  For nested keyed files, the sub key pairs
may be specified in any order and not all pairs have to be specified.

フラットとネストしたキーのファイルは、単一のキーに対する値のみを一度に
書き込めます。ネストしたキーのファイルは、サブキーペアは何らかの命令で
指定できるかもしれない。また、全てのペアが指定されなくても良いかもしれ
ない。

5-3-2. Control Knobs

- Settings for a single feature should generally be implemented in a
  single file.

- In general, the root cgroup should be exempt from resource control
  and thus shouldn't have resource control knobs.

- If a controller implements ratio based resource distribution, the
  control knob should be named "weight" and have the range [1, 10000]
  and 100 should be the default value.  The values are chosen to allow
  enough and symmetric bias in both directions while keeping it
  intuitive (the default is 100%).

- If a controller implements an absolute resource guarantee and/or
  limit, the control knobs should be named "min" and "max"
  respectively.  If a controller implements best effort resource
  gurantee and/or limit, the control knobs should be named "low" and
  "high" respectively.

  In the above four control files, the special token "max" should be
  used to represent upward infinity for both reading and writing.

- If a setting has configurable default value and specific overrides,
  the default settings should be keyed with "default" and appear as
  the first entry in the file.  Specific entries can use "default" as
  its value to indicate inheritance of the default value.
  
5-4. Per-Controller Changes

5-4-1. io

- blkio is renamed to io.  The interface is overhauled anyway.  The
  new name is more in line with the other two major controllers, cpu
  and memory, and better suited given that it may be used for cgroup
  writeback without involving block layer.

- blkio は io にリネームされました。インターフェースは全面的に見直され
  ました。新しい名前は他のふたつのメジャーなコントローラである、CPU、
  メモリにより協調するものです。そしてブロックレイヤーを介さずに
  cgroup writeback に使うのにより適しています。

- Everything including stat is always hierarchical making separate
  recursive stat files pointless and, as no internal node can have
  tasks, leaf weights are meaningless.  The operation model is
  simplified and the interface is overhauled accordingly.

- stat を含むすべてが、別々の再帰的な stat ファイルが無意味となるよう
  に常に階層的です。内部的なノードはタスクを持てませんので、リーフのウェ
  イトは無意味となります。この操作モデルは簡素化されており、インター
  フェースは適切に見直されています。

  io.stat

	The stat file.  The reported stats are from the point where
	bio's are issued to request_queue.  The stats are counted
	independent of which policies are enabled.  Each line in the
	file follows the following format.  More fields may later be
	added at the end.

	  $MAJ:$MIN rbytes=$RBYTES wbytes=$WBYTES rios=$RIOS wrios=$WIOS

	統計 (stat) ファイルです。報告される統計は bio が
	request_queue に対して発行された時点からのものです。統計は有効
	になっているポリシーと独立してカウントされます。ファイル内のそ
	れぞれの行は後述のフォーマットで続きます。複数のフィールドは最
	後に追加されます。

	  $MAJ:$MIN rbytes=$RBYTES wbytes=$WBYTES rios=$RIOS wrios=$WIOS

  io.weight

	The weight setting, currently only available and effective if
	cfq-iosched is in use for the target device.  The weight is
	between 1 and 10000 and defaults to 100.  The first line
	always contains the default weight in the following format to
	use when per-device setting is missing.

	ウェイトの設定で、現時点では cfq-iosched がターゲットのデバイ
	スで使われている場合のみ有効で効果があります。ウェイトは 1 か
	ら 10000 の間で、デフォルトは 100 です。最初の行は常に以下の
	フォーマットのデフォルトのウェイトです。これはデバイスごとの設
	定がない場合に使われます。

	  default $WEIGHT

	Subsequent lines list per-device weights of the following
	format.

	次の行は以下のフォーマットのデバイスごとのウェイトのリストです。

	  $MAJ:$MIN $WEIGHT

	Writing "$WEIGHT" or "default $WEIGHT" changes the default
	setting.  Writing "$MAJ:$MIN $WEIGHT" sets per-device weight
	while "$MAJ:$MIN default" clears it.

	"$WEIGHT" または "default $WEIGHT" を書きこむと、デフォルト値
	が変更されます。"$MAJ:$MIN $WEIGHT" を設定すると、"$MAJ:$MIN
	default" がクリアされて、デバイスごとのウェイトが設定されます。

	This file is available only on non-root cgroups.

	このファイルはルート以外の cgroup でのみ使えます。

  io.max

	The maximum bandwidth and/or iops setting, only available if
	blk-throttle is enabled.  The file is of the following format.

	帯域幅もしくは IOPS の最大値の設定です。blk-throttleが有効な場
	合のみ使えます。ファイルは以下のフォーマットになります。

	  $MAJ:$MIN rbps=$RBPS wbps=$WBPS riops=$RIOPS wiops=$WIOPS

	${R|W}BPS are read/write bytes per second and ${R|W}IOPS are
	read/write IOs per second.  "max" indicates no limit.  Writing
	to the file follows the same format but the individual
	settings may be omitted or specified in any order.

	${R|W}BPS は秒あたりの読みこみ／書きこみのバイト数で、${R|W}
	は秒あたりの読みこみ／書きこみ IOPS です。"max" は制限なしを示
	します。ファイルへの書きこみは同じフォーマットに従いますが、個
	別の設定は省略したり、任意の順番で指定できます。

	This file is available only on non-root cgroups.

	このファイルはルート cgroup 以外でのみ利用できます。

5-4-2. cpuset

- Tasks are kept in empty cpusets after hotplug and take on the masks
  of the nearest non-empty ancestor, instead of being moved to it.

- A task can be moved into an empty cpuset, and again it takes on the
  masks of the nearest non-empty ancestor.


5-4-3. memory

- use_hierarchy is on by default and the cgroup file for the flag is
  not created.

- The original lower boundary, the soft limit, is defined as a limit
  that is per default unset.  As a result, the set of cgroups that
  global reclaim prefers is opt-in, rather than opt-out.  The costs
  for optimizing these mostly negative lookups are so high that the
  implementation, despite its enormous size, does not even provide the
  basic desirable behavior.  First off, the soft limit has no
  hierarchical meaning.  All configured groups are organized in a
  global rbtree and treated like equal peers, regardless where they
  are located in the hierarchy.  This makes subtree delegation
  impossible.  Second, the soft limit reclaim pass is so aggressive
  that it not just introduces high allocation latencies into the
  system, but also impacts system performance due to overreclaim, to
  the point where the feature becomes self-defeating.

  The memory.low boundary on the other hand is a top-down allocated
  reserve.  A cgroup enjoys reclaim protection when it and all its
  ancestors are below their low boundaries, which makes delegation of
  subtrees possible.  Secondly, new cgroups have no reserve per
  default and in the common case most cgroups are eligible for the
  preferred reclaim pass.  This allows the new low boundary to be
  efficiently implemented with just a minor addition to the generic
  reclaim code, without the need for out-of-band data structures and
  reclaim passes.  Because the generic reclaim code considers all
  cgroups except for the ones running low in the preferred first
  reclaim pass, overreclaim of individual groups is eliminated as
  well, resulting in much better overall workload performance.

- The original high boundary, the hard limit, is defined as a strict
  limit that can not budge, even if the OOM killer has to be called.
  But this generally goes against the goal of making the most out of
  the available memory.  The memory consumption of workloads varies
  during runtime, and that requires users to overcommit.  But doing
  that with a strict upper limit requires either a fairly accurate
  prediction of the working set size or adding slack to the limit.
  Since working set size estimation is hard and error prone, and
  getting it wrong results in OOM kills, most users tend to err on the
  side of a looser limit and end up wasting precious resources.

  The memory.high boundary on the other hand can be set much more
  conservatively.  When hit, it throttles allocations by forcing them
  into direct reclaim to work off the excess, but it never invokes the
  OOM killer.  As a result, a high boundary that is chosen too
  aggressively will not terminate the processes, but instead it will
  lead to gradual performance degradation.  The user can monitor this
  and make corrections until the minimal memory footprint that still
  gives acceptable performance is found.

  In extreme cases, with many concurrent allocations and a complete
  breakdown of reclaim progress within the group, the high boundary
  can be exceeded.  But even then it's mostly better to satisfy the
  allocation from the slack available in other groups or the rest of
  the system than killing the group.  Otherwise, memory.max is there
  to limit this type of spillover and ultimately contain buggy or even
  malicious applications.

- The original control file names are unwieldy and inconsistent in
  many different ways.  For example, the upper boundary hit count is
  exported in the memory.failcnt file, but an OOM event count has to
  be manually counted by listening to memory.oom_control events, and
  lower boundary / soft limit events have to be counted by first
  setting a threshold for that value and then counting those events.
  Also, usage and limit files encode their units in the filename.
  That makes the filenames very long, even though this is not
  information that a user needs to be reminded of every time they type
  out those names.

  To address these naming issues, as well as to signal clearly that
  the new interface carries a new configuration model, the naming
  conventions in it necessarily differ from the old interface.

- The original limit files indicate the state of an unset limit with a
  Very High Number, and a configured limit can be unset by echoing -1
  into those files.  But that very high number is implementation and
  architecture dependent and not very descriptive.  And while -1 can
  be understood as an underflow into the highest possible value, -2 or
  -10M etc. do not work, so it's not consistent.

  memory.low, memory.high, and memory.max will use the string "max" to
  indicate and set the highest possible value.


5. Planned Changes

5-1. CAP for resource control

Unified hierarchy will require one of the capabilities(7), which is
yet to be decided, for all resource control related knobs.  Process
organization operations - creation of sub-cgroups and migration of
processes in sub-hierarchies may be delegated by changing the
ownership and/or permissions on the cgroup directory and
"cgroup.procs" interface file; however, all operations which affect
resource control - writes to "cgroup.subtree_control" or any
controller-specific knobs - will require an explicit CAP privilege.

単一階層構造には、まだ決定していないが、全てのリソースコントロールに関
係するノブに、ケーパビリティがひとつ必要になるだろう。サブグループの作
成やサブ階層へのマイグレーションと言ったようなプロセスの集合に対する操
作は cgroup ディレクトリや "cgroup.procs" の所有権やパーミッションを変
えることによって伝播する可能性がある。一方、リソースコントロールに影響
する全ての操作、つまり "cgroup.subtree_control" や任意のコントローラ特
有のノブに対する書き込みのような操作は、明確 CAP 特権が必要となるだろう。

This, in part, is to prevent cgroup interface from being inadvertently
promoted to programmable API used by non-privileged binaries.  cgroup
exposes various aspects of the system in ways which aren't properly
abstracted for direct consumption by regular programs.  This is an
administration interface much closer to sysctl knobs than system
calls.  Even the basic access model, being filesystem path based,
isn't suitable for direct consumption.  There's no way to access "my
cgroup" in race-free way or make multiple operations atomic against
migration to another cgroup.

これはある程度、cgroup インターフェースの、非特権バイナリが使うプログ
ラマブル API に対する意図しない昇格を防ぐためのものである。cgroup は通
常のプログラムの消費を直接、適切に抽象化されない方法でシステムの色々な側
面を露出している。これはシステムコールよりも sysctl ノブに近い管理イン
ターフェースである。ファイルシステムのパスベースの通常のアクセスモデル
は、直接の消費には向いていない。競合のない方法で「私のcgroup」にア
クセスする方法がなく、他のcgroupへのマイグレーションに対する複数の操作
をアトミックにする方法もない。

Another aspect is that, for better or for worse, cgroup interface goes
through far less scrutiny than regular interfaces for unprivileged
userland.  The upside is that cgroup is able to expose useful features
which may not be suitable for general consumption in reasonable time
frame.  It provides a relatively short path between internal details
and userland-visible interface.  Of course, this shortcut comes with
high risk.  We go through what we go through for general kernel APIs
for good reasons.  It may end up leaking internal details in a way
which can exert significant pain by locking the kernel into a contract
that can't be maintained in a reasonable manner.

別の側面は、良きにせよ悪しきにせよ、cgroup インターフェースは非特権ユー
ザランドに対する通常のインターフェースに比べてはるかに精密でなく使うこ
とができる。この良い面は、妥当な時間枠内での一般的な消費に対して適切で
ない可能性のある有用な機能を見せることができることである。これは比較的
最短経路で内部の詳細とユーザランドで見ることのできるインターフェースを
提供する。もちろん、このショートカットは高いリスクを伴う。我々は正当な
理由で一般的なカーネル API を通したものを通します。これは、妥当な方法
で扱うことができない決まりでカーネルを閉じ込める事により、重大な痛みを
行使する可能性のある方法で最終的には内部の詳細なリークとなるかもしれな
い。

Also, due to the specific nature, cgroup and its controllers don't
tend to attract attention from wide-scope of developers.  cgroup's
short history is already fraught with severely mis-designed
interfaces, unnecessary commitment to and exposing of internal
details, broken and dangerous implementations of various features.

また、この特有の性質により、cgroup とコントローラは開発者の広いスコー
プから注意を引きつけない傾向がある。cgroup の小史は厳しくミスデザイン
されたインターフェース、不必要なコミットと内部の詳細の公開、様々な機能
の壊れた危険な実装で既に困難なものである。

Keeping cgroup as an administration interface is both advantageous for
its role and an imperative given its nature.  Some of the cgroup
features may make sense for unprivileged access.  If deemed justified,
those must be further abstracted and implemented as a different
interface, be it a system call or process-private filesystem, and
survive through the scrutiny that any interface for general
consumption is required to go through.

cgroup を管理インターフェースとして維持し続けることは、その役割が得に
なる事と、与えられたその性質が不可欠であることの両方である。cgroup の
機能には、非特権アクセスの意味がある可能性があるものがある。もし理にか
なっていると考えるのなら、より抽象化され、システムコールやプロセス独自
のファイルシステムのような異なるインターフェースで実装され、一般的な消
費が通ることが必要な任意のインターフェースの精査を通して存続し続けなけ
ればならない。

Requiring CAP is not a complete solution but should serve as a
significant deterrent against spraying cgroup usages in non-privileged
programs.

CAPの必要性は完全な解決策ではない。しかし非特権プログラムのスプレーす
るような cgroup の使用に対する重要な抑止力としての役割を果たすだろう。