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

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

Availability: Unix, 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` を送出します。

  Availability: Linux >= 2.6.36 with glibc >= 2.13.

  Added in version 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

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

  Availability: FreeBSD >= 11.

resource.RLIMIT_AS

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

resource.RLIMIT_MSGQUEUE

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

  Availability: Linux >= 2.6.8.

  Added in version 3.4.

resource.RLIMIT_NICE

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

  Availability: Linux >= 2.6.12.

  Added in version 3.4.

resource.RLIMIT_RTPRIO

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

  Availability: Linux >= 2.6.12.

  Added in version 3.4.

resource.RLIMIT_RTTIME

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

  Availability: Linux >= 2.6.25.

  Added in version 3.4.

resource.RLIMIT_SIGPENDING

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

  Availability: Linux >= 2.6.8.

  Added in version 3.4.

resource.RLIMIT_SBSIZE

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

  Availability: FreeBSD.

  Added in version 3.4.

resource.RLIMIT_SWAP

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

  Availability: FreeBSD.

  Added in version 3.4.

resource.RLIMIT_NPTS

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

  Availability: FreeBSD.

  Added in version 3.4.

resource.RLIMIT_KQUEUES

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

  Availability: FreeBSD >= 11.

  Added in version 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()` に渡すと現在のスレッドが消費しているリソースを要求します。全てのシステムで利用可能なわけではありません。

  Added in version 3.2.