Documentation/cgroups/resource_counter.txt をテキトーに翻訳
Linux 3.3 に付属していたものを勢いで翻訳しました．
- 一切見直しとかしてませんので，間違ってる場合も多いかと思います．
- 用語の統一とかもしてません．
The Resource Counter
リソースカウンタ
The resource counter, declared at include/linux/res_counter.h,
is supposed to facilitate the resource management by controllers
by providing common stuff for accounting.
include/linux/res_counter.h で宣言されているリソースカウンタは，アカ
ウンティングのための共通の stuff を提供するコントローラによるリソース管理
を容易にするものである．
This "stuff" includes the res_counter structure and routines
to work with it.
ここでいう "stuff" は res_counter 構造体と，それと共に動くルーティンを
含む．
1. Crucial parts of the res_counter structure
1. res_counter 構造体の重要な部分
a. unsigned long long usage
The usage value shows the amount of a resource that is consumed
by a group at a given time. The units of measurement should be
determined by the controller that uses this counter. E.g. it can
be bytes, items or any other unit the controller operates on.
usage 値は，所定の時間内にグループが消費したリソースの量を現し
ている．測定単位は，このカウンターを使うコントローラが定義すべ
きである．例えば，バイト，item 数や，コントローラが扱う他の単
位を取る事が可能である．
b. unsigned long long max_usage
The maximal value of the usage over time.
今までの使用量の最大値．
This value is useful when gathering statistical information about
the particular group, as it shows the actual resource requirements
for a particular group, not just some usage snapshot.
この値は，瞬間の使用量のスナップショットではなく，特定のグルー
プが実際に必要としているリソースを示すというような，特定のグルー
プの統計情報を集める際に役に立つ．
c. unsigned long long limit
The maximal allowed amount of resource to consume by the group. In
case the group requests for more resources, so that the usage value
would exceed the limit, the resource allocation is rejected (see
the next section).
グループが消費可能なリソースの最大値．グループが更なるリソース
を要求する際に，リソース割り当ては拒否される (次項参照)．
d. unsigned long long failcnt
The failcnt stands for "failures counter". This is the number of
resource allocation attempts that failed.
failcnt は "失敗カウンタ" をあらわす．これはリソース割り当ての
試みが失敗した回数を示す．
c. spinlock_t lock
Protects changes of the above values.
前述の値の変更を保護する．
2. Basic accounting routines
2. 基本アカウンティングルーティン
a. void res_counter_init(struct res_counter *rc,
struct res_counter *rc_parent)
Initializes the resource counter. As usual, should be the first
routine called for a new counter.
リソースカウンタを初期化する．通常，新しいカウンタを呼び出す際
は最初に呼ばれるべきものである．
The struct res_counter *parent can be used to define a hierarchical
child -> parent relationship directly in the res_counter structure,
NULL can be used to define no relationship.
res_counter 構造体である *parent は，res_counter 構造体内で直
接，子→親の関係の階層構造を定義するのに使う．
c. int res_counter_charge(struct res_counter *rc, unsigned long val,
struct res_counter **limit_fail_at)
When a resource is about to be allocated it has to be accounted
with the appropriate resource counter (controller should determine
which one to use on its own). This operation is called "charging".
リソースが割り当てられようとしている時，その割り当ては適切なリ
ソースカウンタにアカウンティングされなければならない (コントロー
ラは自身で使うカウンタを定義する必要がある)．
This is not very important which operation - resource allocation
or charging - is performed first, but
どのオペレーションを最初に実行するかは重要ではないが，
* if the allocation is performed first, this may create a
temporary resource over-usage by the time resource counter is
charged;
* もし割り当てが最初に実行されるなら，リソースカウンタがチャー
ジされるまでは，一時的にリソースが過剰に使用されるかもしれ
ない．
* if the charging is performed first, then it should be uncharged
on error path (if the one is called).
* もしチャージが先に実行されるなら，もし処理が呼ばれた時のエ
ラーパスとしてアンチャージを行う必要がある．
If the charging fails and a hierarchical dependency exists, the
limit_fail_at parameter is set to the particular res_counter element
where the charging failed.
もしチャージの失敗と，階層構造の依存性が存在する場合，
limit_fail_at パラメータにチャージが失敗した特定の res_counter
要素をセットする．
d. int res_counter_charge_locked
(struct res_counter *rc, unsigned long val)
The same as res_counter_charge(), but it must not acquire/release the
res_counter->lock internally (it must be called with res_counter->lock
held).
res_counter_charge と同様だが，内部的に res_counter->lock を取
得したり開放してはいけない (res_counter->lock を保持した状態で
呼び出さなければならない)
e. void res_counter_uncharge[_locked]
(struct res_counter *rc, unsigned long val)
When a resource is released (freed) it should be de-accounted
from the resource counter it was accounted to. This is called
"uncharging".
リソースがリリース (開放) された時，アカウンティングされたリソー
スカウンタから減らす必要がある．これを "アンチャージング
(uncharging)" と呼ぶ．
The _locked routines imply that the res_counter->lock is taken.
_locked ルーティンは res_counter->lock が取得されている事を示し
ている．
2.1 Other accounting routines
2.1 他のアカウンティングルーティン
There are more routines that may help you with common needs, like
checking whether the limit is reached or resetting the max_usage
value. They are all declared in include/linux/res_counter.h.
他にも制限に到達したかどうかをチェックしたり，max_usage 値をリセッ
トしたりするような，共通のニーズを助けるルーティンが存在する．これ
らは全て include/linux/res_counter.h で宣言されている．
3. Analyzing the resource counter registrations
3. リソースカウンタ登録の解析
a. If the failcnt value constantly grows, this means that the counter's
limit is too tight. Either the group is misbehaving and consumes too
many resources, or the configuration is not suitable for the group
and the limit should be increased.
a. もし failcnt の値がコンスタントに増加している場合，カウンタの制限
値が厳しすぎる事を意味します．グループが不当にリソースを消費する動
きをしているか，設定がグループに合っていないかので，制限を増加させ
る必要があるかのどちらかです．
b. The max_usage value can be used to quickly tune the group. One may
set the limits to maximal values and either load the container with
a common pattern or leave one for a while. After this the max_usage
value shows the amount of memory the container would require during
its common activity.
max_usage の値は，グループを素早くチューンするのに使用できます．最
大値に制限をセットして，共通のパターンでコンテナをロードするか，し
ばらくの間放置しても良い．この後，max_usage の値は，通常の稼働状態
で必要とするメモリの量を示すだろう．
Setting the limit a bit above this value gives a pretty good
configuration that works in most of the cases.
この値の少し前で制限を設定すると，大体の場合で適切に働く良い設定と
なる．
c. If the max_usage is much less than the limit, but the failcnt value
is growing, then the group tries to allocate a big chunk of resource
at once.
c. もし max_usage が制限よりはるかに小さいが，failcnt の値が増加して
いる場合は，グループが一度に大量の割り当てを行おうとしている．
d. If the max_usage is much less than the limit, but the failcnt value
is 0, then this group is given too high limit, that it does not
require. It is better to lower the limit a bit leaving more resource
for other groups.
d. もし max_usage が制限よりはるかに小さく，failcnt が 0 の場合で，グ
ループに大きな値の制限を設定している場合，そのような制限は不要であ
る．更に低い制限値を設定し，他のグループのリソース制限を少し緩和す
るのが良いだろう．
4. Communication with the control groups subsystem (cgroups)
4. control group サブシステムとのコミュニケーション
All the resource controllers that are using cgroups and resource counters
should provide files (in the cgroup filesystem) to work with the resource
counter fields. They are recommended to adhere to the following rules:
cgroup を使っている全てのリソースコントローラとリソースカウンタは，リ
ソースカウンターの値と連携するファイルを (cgroup ファイルシステム上に)
提供する必要がある．後述のルールに従う事が推奨されている．
a. File names
Field name File name
---------------------------------------------------
usage usage_in_<unit_of_measurement>
max_usage max_usage_in_<unit_of_measurement>
limit limit_in_<unit_of_measurement>
failcnt failcnt
lock no file :)
b. Reading from file should show the corresponding field value in the
appropriate format.
b. ファイルからの読み取りは，適切なフォーマットで一致するフィールドの
値を表示する必要がある．
c. Writing to file
Field Expected behavior
----------------------------------
usage prohibited
max_usage reset to usage
limit set the limit
failcnt reset to zero
5. Usage example
a. Declare a task group (take a look at cgroups subsystem for this) and
fold a res_counter into it
a. タスクグループを宣言し (参考に cgroup サブシステムをざっと眺めてみ
よう)，その中に res_counter を収める．
struct my_group {
struct res_counter res;
<other fields>
}
b. Put hooks in resource allocation/release paths
b. リソースの割り当て，開放パス内にフックを置く
int alloc_something(...)
{
if (res_counter_charge(res_counter_ptr, amount) < 0)
return -ENOMEM;
<allocate the resource and return to the caller>
}
void release_something(...)
{
res_counter_uncharge(res_counter_ptr, amount);
<release the resource>
}
In order to keep the usage value self-consistent, both the
"res_counter_ptr" and the "amount" in release_something() should be
the same as they were in the alloc_something() when the releasing
resource was allocated.
一貫性のある usage の値をキープするために，release_something() 内
の "res_counter_ptr" と "amount" の両方は，公開された時にリソース
を割り当てた時の alloc_something() 内のそれらと同じでなければいけ
ません．
c. Provide the way to read res_counter values and set them (the cgroups
still can help with it).
c. res_counter の値を読む方法と，セットする方法を提供する (cgroup が
それを助けてくれます)
c. Compile and run :)
c. コンパイルして実行 :)