36.13. "resource" --- リソース使用状態の情報
********************************************

このモジュールでは、プログラムによって使用されているシステムリソースを
計測したり制御するための基本的なメカニズムを提供します。

特定のシステムリソースを指定したり、現在のプロセスやその子プロセスのリ
ソース使用情報を要求するためにシンボル定数が使われます。

エラーを表すための例外が一つ定義されています:

exception resource.error

   下に述べる関数は、背後にあるシステムコールが予期せず失敗した場合、
   このエラーを送出するかもしれません。


36.13.1. リソースの制限
=======================

リソースの使用は下に述べる "setrlimit()" 関数を使って制限することがで
きます。各リソースは二つ組の制限値: ソフトリミット (soft limit) 、およ
びハードリミット (hard limit) 、で制御されます。ソフトリミットは現在の
制限値で、時間とともにプロセスによって下げたり上げたりできます。ソフト
リミットはハードリミットを超えることはできません。ハードリミットはソフ
トリミットよりも高い任意の値まで下げることができますが、上げることはで
きません。 (スーパユーザの有効な UID を持つプロセスのみがハードリミッ
トを上げることができます。)

制限をかけるべく指定できるリソースはシステムに依存します。指定できるリ
ソースは *getrlimit(2)* マニュアルページで解説されています。以下に列挙
するリソースは背後のオペレーティングシステムがサポートする場合にサポー
トされています; オペレーティングシステム側で値を調べたり制御したりでき
ないリソースは、そのプラットフォーム向けのこのモジュール内では定義され
ていません。

resource.RLIM_INFINITY

   無制限のリソースの上限を示すための定数です。

resource.getrlimit(resource)

   *resource* の現在のソフトおよびハードリミットを表すタプル "(soft,
   hard)" を返します。無効なリソースが指定された場合には "ValueError"
   が、背後のシステムコールが予期せず失敗した場合には "error" が送出さ
   れます。

resource.setrlimit(resource, limits)

   *resouce* の新たな消費制限を設定します。 *limits* 引数には、タプル
   "(soft, hard)" による二つの整数で、新たな制限を記述しなければなりま
   せん。 "RLIM_INFINITY" を指定することで、無制限を要求することが出来
   ます。

   無効なリソースが指定された場合、ソフトリミットの値がハードリミット
   の値を超えている場合、プロセスがハードリミットを引き上げようとした
   場合には "ValueError" が送出されます。リソースのハードリミットやシ
   ステムリミットが無制限でないのに "RLIM_INFINITY" を指定した場合も、
   "ValueError" になります。スーパーユーザの実効 UID を持ったプロセス
   は無制限を含めあらゆる妥当な制限値を要求出来ますが、システムが課し
   ている制限を超過した要求ではやはり "ValueError" となります。

   "setrlimit" は背後のシステムコールが予期せず失敗した場合に、
   "error" を送出する場合があります。

以下のシンボルは、後に述べる関数 "setrlimit()" および "getrlimit()" を
使って消費量を制御することができるリソースを定義しています。これらのシ
ンボルの値は、C プログラムで使われているシンボルと全く同じです。

*getrlimit(2)* の Unix マニュアルページには、指定可能なリソースが列挙
されています。全てのシステムで同じシンボルが使われているわけではなく、
また同じリソースを表すために同じ値が使われているとも限らないので注意し
てください。このモジュールはプラットフォーム間の相違を隠蔽しようとはし
ていません --- あるプラットフォームで定義されていないシンボルは、その
プラットフォーム向けの本モジュールでは利用することができません。

resource.RLIMIT_CORE

   現在のプロセスが生成できるコアファイルの最大 (バイト) サイズです。
   プロセスの全体イメージを入れるためにこの値より大きなサイズのコアフ
   ァイルが要求された結果、部分的なコアファイルが生成される可能性があ
   ります。

resource.RLIMIT_CPU

   プロセッサが利用することができる最大プロセッサ時間 (秒) です。この
   制限を超えた場合、 "SIGXCPU" シグナルがプロセスに送られます。 (どの
   ようにしてシグナルを捕捉したり、例えば開かれているファイルをディス
   クにフラッシュするといった有用な処理を行うかについての情報は、
   "signal" モジュールのドキュメントを参照してください)

resource.RLIMIT_FSIZE

   プロセスが作成するファイルの最大サイズです。

resource.RLIMIT_DATA

   プロセスのヒープの最大 (バイト) サイズです。

resource.RLIMIT_STACK

   現在のプロセスのコールスタックの最大サイズ (バイト単位) です。 これ
   はマルチスレッドプロセスのメインスレッドのスタックのみに影響します
   。

resource.RLIMIT_RSS

   プロセスが取りうる最大 RAM 常駐ページサイズ (resident set size) で
   す。

resource.RLIMIT_NPROC

   現在のプロセスが生成できるプロセスの上限です。

resource.RLIMIT_NOFILE

   現在のプロセスが開けるファイル記述子の上限です。

resource.RLIMIT_OFILE

   "RLIMIT_NOFILE" の BSD での名称です。

resource.RLIMIT_MEMLOCK

   メモリ中でロックできる最大アドレス空間です。

resource.RLIMIT_VMEM

   プロセスが占有できるマップメモリの最大領域です。

resource.RLIMIT_AS

   アドレス空間でプロセスが占有できる最大領域 (バイト) です。


36.13.2. リソースの使用状態
===========================

以下の関数はリソース使用情報を取得するために使われます:

resource.getrusage(who)

   この関数は、 *who* 引数で指定される、現プロセスおよびその子プロセス
   によって消費されているリソースを記述するオブジェクトを返します。
   *who* 引数は以下に記述される "RUSAGE_*" 定数のいずれかを使って指定
   します。

   返される値の各フィールドはそれぞれ、個々のシステムリソースがどれく
   らい使用されているか、例えばユーザモードでの実行に費やされた時間や
   プロセスが主記憶からスワップアウトされた回数、を示しています。幾つ
   かの値、例えばプロセスが使用しているメモリ量は、内部時計の最小単位
   に依存します。

   以前のバージョンとの互換性のため、返される値は 16 要素からなるタプ
   ルとしてアクセスすることもできます。

   戻り値のフィールド "ru_utime" および "ru_stime" は浮動小数点数で、
   それぞれユーザモードでの実行に費やされた時間、およびシステムモード
   での実行に費やされた時間を表します。それ以外の値は整数です。これら
   の値に関する詳しい情報は *getrusage(2)* を調べてください。以下に簡
   単な概要を示します:

   +----------+-----------------------+---------------------------------+
   | インデッ | フィールド            | リソース                        |
   | クス     |                       |                                 |
   +==========+=======================+=================================+
   | "0"      | "ru_utime"            | ユーザモード実行時間 (float)    |
   +----------+-----------------------+---------------------------------+
   | "1"      | "ru_stime"            | システムモード実行時間 (float)  |
   +----------+-----------------------+---------------------------------+
   | "2"      | "ru_maxrss"           | 最大常駐ページサイズ            |
   +----------+-----------------------+---------------------------------+
   | "3"      | "ru_ixrss"            | 共有メモリサイズ                |
   +----------+-----------------------+---------------------------------+
   | "4"      | "ru_idrss"            | 非共有メモリサイズ              |
   +----------+-----------------------+---------------------------------+
   | "5"      | "ru_isrss"            | 非共有スタックサイズ            |
   +----------+-----------------------+---------------------------------+
   | "6"      | "ru_minflt"           | I/O を必要としないページフォー  |
   |          |                       | ルト数                          |
   +----------+-----------------------+---------------------------------+
   | "7"      | "ru_majflt"           | I/O を必要とするページフォール  |
   |          |                       | ト数                            |
   +----------+-----------------------+---------------------------------+
   | "8"      | "ru_nswap"            | スワップアウト回数              |
   +----------+-----------------------+---------------------------------+
   | "9"      | "ru_inblock"          | ブロック入力操作数              |
   +----------+-----------------------+---------------------------------+
   | "10"     | "ru_oublock"          | ブロック出力操作数              |
   +----------+-----------------------+---------------------------------+
   | "11"     | "ru_msgsnd"           | 送信メッセージ数                |
   +----------+-----------------------+---------------------------------+
   | "12"     | "ru_msgrcv"           | 受信メッセージ数                |
   +----------+-----------------------+---------------------------------+
   | "13"     | "ru_nsignals"         | 受信シグナル数                  |
   +----------+-----------------------+---------------------------------+
   | "14"     | "ru_nvcsw"            | 自発的な実行コンテキスト切り替  |
   |          |                       | え数                            |
   +----------+-----------------------+---------------------------------+
   | "15"     | "ru_nivcsw"           | 非自発的な実行コンテキスト切り  |
   |          |                       | 替え数                          |
   +----------+-----------------------+---------------------------------+

   この関数は無効な *who* 引数を指定した場合には "ValueError" を送出し
   ます。また、異常が発生した場合には "error" 例外が送出される可能性が
   あります。

   バージョン 2.3 で変更: 値へのアクセスを戻り値の属性として追加しまし
   た。

resource.getpagesize()

   システムページ内のバイト数を返します。(ハードウェアページサイズと同
   じとは限りません。)

以下の "RUSAGE_*" シンボルはどのプロセスの情報を提供させるかを指定する
ために関数 "getrusage()" に渡されます。

resource.RUSAGE_SELF

   "RUSAGE_SELF" はプロセス自体のみに属する情報を要求するために使われ
   ます。

resource.RUSAGE_CHILDREN

   "getrusage()"  に渡すと呼び出し側プロセスの子プロセスのリソース情報
   を要求します。

resource.RUSAGE_BOTH

   "getrusage()" に渡すと現在のプロセスおよび子プロセスの両方が消費し
   ているリソースを要求します。全てのシステムで利用可能なわけではあり
   ません。
