"resource" --- Resource usage information
*****************************************

======================================================================

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

Availability: Unix, not Emscripten, not WASI.

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

システムコールが失敗した場合 "OSError" を送出します。

exception resource.error

   "OSError" の非推奨のエイリアスです。

   バージョン 3.3 で変更: **PEP 3151** に基づき、このクラスは
   "OSError" のエイリアスになりました。


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

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

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

resource.RLIM_INFINITY

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

resource.getrlimit(resource)

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

resource.setrlimit(resource, limits)

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

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

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

   VxWorks only supports setting "RLIMIT_NOFILE".

   引数 "src", "dst`, ``limits" を指定して 監査イベント
   "resource.setrlimit" を送出します。

resource.prlimit(pid, resource[, limits])

   1つの関数の中で "setrlimit()" と "getrlimit()" を組み合わせ、任意の
   プロセスのリソースの制限値を取得したり設定したりします。 *pid* が 0
   の場合は、現在のプロセスに適用されます。 *resource* および *limits*
   は、 *limits* がオプションであることを除けば、 "setrlimit()" と同じ
   意味です。

   *limits* が与えられないときは、関数はプロセス *pid* の *resource*
   の制限値を返します。 *limits* が与えられたときは、プロセスの
   *resource* の制限値が設定され、設定が変更される前のリソースの制限値
   が返されます。

   *pid* が見付からないときは "ProcessLookupError" を、ユーザがプロセ
   スの "CAP_SYS_RESOURCE" を持ってないときは "PermissionError" を送出
   します。

   引数 "pid", "dst`, ``limits" を指定して 監査イベント
   "resource.prlimit" を送出します。

   利用可能な環境: Linux >= 2.6.36 かつ glibc >= 2.13.

   バージョン 3.4 で追加.

以下のシンボルは、後に述べる関数 "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

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

   利用可能な環境: FreeBSD 11 以上。

resource.RLIMIT_AS

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

resource.RLIMIT_MSGQUEUE

   POSIX メッセージキューに割り当てることの出来るバイト数です。

   利用可能な環境: Linux 2.6.8以上。

   バージョン 3.4 で追加.

resource.RLIMIT_NICE

   プロセスの nice の上限です (20 - rlim_cur)。

   利用可能な環境: Linux 2.6.12以上。

   バージョン 3.4 で追加.

resource.RLIMIT_RTPRIO

   リアルタイム優先順位の上限です。

   利用可能な環境: Linux 2.6.12以上。

   バージョン 3.4 で追加.

resource.RLIMIT_RTTIME

   リアルタイムスケジューリングにおいて、プロセスがブロッキングシステ
   ムコールを行わずに使用できるCPU時間の制限値（マイクロ秒単位）。

   利用可能な環境: Linux 2.6.25以上。

   バージョン 3.4 で追加.

resource.RLIMIT_SIGPENDING

   プロセスがキュー出来るシグナルの数です。

   利用可能な環境: Linux 2.6.8以上。

   バージョン 3.4 で追加.

resource.RLIMIT_SBSIZE

   このユーザが使用するソケットバッファの最大サイズ(バイト単位)。これ
   は、このユーザが常に保持できるネットワークメモリの量、つまり mbuf
   の量を制限します。

   利用可能な環境: FreeBSD。

   バージョン 3.4 で追加.

resource.RLIMIT_SWAP

   このユーザ ID のすべてのプロセスで予約または使用できるスワップスペ
   ースの最大サイズ (バイト単位)。この制限は vm.overcommit sysctl のビ
   ット 1 が設定されている場合のみ適用されます。この sysctl の完全な説
   明については tuning(7) を参照してください。

   利用可能な環境: FreeBSD。

   バージョン 3.4 で追加.

resource.RLIMIT_NPTS

   このユーザ ID が作成する擬似端末の数の上限です。

   利用可能な環境: FreeBSD。

   バージョン 3.4 で追加.

resource.RLIMIT_KQUEUES

   The maximum number of kqueues this user id is allowed to create.

   利用可能な環境: FreeBSD 11 以上。

   バージョン 3.10 で追加.


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

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

resource.getrusage(who)

   This function returns an object that describes the resources
   consumed by either the current process or its children, as
   specified by the *who* parameter.  The *who* parameter should be
   specified using one of the "RUSAGE_*" constants described below.

   簡単な例:

      from resource import *
      import time

      # a non CPU-bound task
      time.sleep(3)
      print(getrusage(RUSAGE_SELF))

      # a CPU-bound task
      for i in range(10 ** 8):
         _ = 1 + 1
      print(getrusage(RUSAGE_SELF))

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

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

   The fields "ru_utime" and "ru_stime" of the return value are
   floating point values representing the amount of time spent
   executing in user mode and the amount of time spent executing in
   system mode, respectively. The remaining values are integers.
   Consult the *getrusage(2)* man page for detailed information about
   these values. A brief summary is presented here:

   +----------+-----------------------+-----------------------------------------+
   | インデッ | フィールド            | リソース                                |
   | クス     |                       |                                         |
   |==========|=======================|=========================================|
   | "0"      | "ru_utime"            | time in user mode (float seconds)       |
   +----------+-----------------------+-----------------------------------------+
   | "1"      | "ru_stime"            | time in system mode (float seconds)     |
   +----------+-----------------------+-----------------------------------------+
   | "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" 例外が送出される可能性が
   あります。

resource.getpagesize()

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

The following "RUSAGE_*" symbols are passed to the "getrusage()"
function to specify which processes information should be provided
for.

resource.RUSAGE_SELF

   "getrusage()" に渡すと呼び出し中のプロセスが消費しているリソースを
   要求します。そのプロセスの全スレッドが使用するリソースの合計です。

resource.RUSAGE_CHILDREN

   呼び出し元のプロセスの子プロセスが消費するリソースを要求するために
   、 "getrusage()" に渡して終了させ、待機させることができます。

resource.RUSAGE_BOTH

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

resource.RUSAGE_THREAD

   "getrusage()" に渡すと現在のスレッドが消費しているリソースを要求し
   ます。全てのシステムで利用可能なわけではありません。

   バージョン 3.2 で追加.
