# `resource` --- リソース使用状態の情報

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

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

システムコールが失敗した場合 `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` を送出します。

  Availability: Linux 2.6.36 or later with glibc 2.13 or later.

  バージョン 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`

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

`resource.``RLIMIT_AS`

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

`resource.``RLIMIT_MSGQUEUE`

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

  Availability: Linux 2.6.8 or later.

  バージョン 3.4 で追加.

`resource.``RLIMIT_NICE`

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

  Availability: Linux 2.6.12 or later.

  バージョン 3.4 で追加.

`resource.``RLIMIT_RTPRIO`

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

  Availability: Linux 2.6.12 or later.

  バージョン 3.4 で追加.

`resource.``RLIMIT_RTTIME`

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

  Availability: Linux 2.6.25 or later.

  バージョン 3.4 で追加.

`resource.``RLIMIT_SIGPENDING`

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

  Availability: Linux 2.6.8 or later.

  バージョン 3.4 で追加.

`resource.``RLIMIT_SBSIZE`

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

  Availability: FreeBSD 9 or later.

  バージョン 3.4 で追加.

`resource.``RLIMIT_SWAP`

  The maximum size (in bytes) of the swap space that may be reserved or used by all of this user id's processes. This limit is enforced only if bit 1 of the vm.overcommit sysctl is set. Please see tuning(7) for a complete description of this sysctl.

  Availability: FreeBSD 9 or later.

  バージョン 3.4 で追加.

`resource.``RLIMIT_NPTS`

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

  Availability: FreeBSD 9 or later.

  バージョン 3.4 で追加.

`resource.``RLIMIT_KQUEUES`

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

  Availability: FreeBSD 11 or later.

  バージョン 3.10 で追加.

## リソースの使用状態

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

`resource.``getrusage`(who)

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

  簡単な例:

      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 要素からなるタプルとしてアクセスすることもできます。

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

  インデックス | フィールド | リソース
  --- | --- | ---
  `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`()

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

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

`resource.``RUSAGE_SELF`

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

`resource.``RUSAGE_CHILDREN`

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

`resource.``RUSAGE_BOTH`

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

`resource.``RUSAGE_THREAD`

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

  バージョン 3.2 で追加.