"resource" --- リソース使用情報
*******************************

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

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

利用可能な環境: Unix, not WASI.

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

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

exception resource.error

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

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


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

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

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

resource.RLIM_INFINITY

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

   バージョン 3.15 で変更: 常に正の値になりました。 以前は -1 や -3 な
   ど、負の値になる場合がありました。

resource.RLIM_SAVED_CUR

resource.RLIM_SAVED_MAX

   C の "rlim_t" の値で表せない場合に、ソフトリミットとハードリミット
   の値を表すために使う定数です。 "RLIM_INFINITY" と等しい場合もありま
   す。

   Added in version 3.15.

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 では "RLIMIT_NOFILE" の設定にのみ対応しています。

   引数 "resource", "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", "resource", "limits" を指定して 監査イベント
   "resource.prlimit" を送出します。

   利用可能な環境: 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

   プロセスが占有できるマップされたメモリ領域の上限です。 通常は
   "RLIMIT_AS" の別名です。

   利用可能な環境: Solaris, FreeBSD, NetBSD.

resource.RLIMIT_AS

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

resource.RLIMIT_MSGQUEUE

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

   利用可能な環境: Linux >= 2.6.8.

   Added in version 3.4.

resource.RLIMIT_NICE

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

   利用可能な環境: Linux >= 2.6.12.

   Added in version 3.4.

resource.RLIMIT_RTPRIO

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

   利用可能な環境: Linux >= 2.6.12.

   Added in version 3.4.

resource.RLIMIT_RTTIME

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

   利用可能な環境: Linux >= 2.6.25.

   Added in version 3.4.

resource.RLIMIT_SIGPENDING

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

   利用可能な環境: Linux >= 2.6.8.

   Added in version 3.4.

resource.RLIMIT_SBSIZE

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

   利用可能な環境: FreeBSD, NetBSD.

   Added in version 3.4.

resource.RLIMIT_SWAP

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

   利用可能な環境: FreeBSD >= 8.

   Added in version 3.4.

resource.RLIMIT_NPTS

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

   利用可能な環境: FreeBSD >= 8.

   Added in version 3.4.

resource.RLIMIT_KQUEUES

   このユーザー ID で作成できる kqueue の数の上限です。

   利用可能な環境: FreeBSD >= 11.

   Added in version 3.10.

resource.RLIMIT_NTHR

   メインスレッドとカーネルスレッドを除き、このユーザー ID が持てるス
   レッド数の上限です。

   利用可能な環境: NetBSD >= 7.0.

   Added in version 3.15.

resource.RLIMIT_PIPEBUF

   このユーザー ID が使用できる、双方向パイプや FIFO 用のカーネル内バ
   ッファの合計サイズの上限です。

   利用可能な環境: FreeBSD >= 14.2.

   Added in version 3.15.

resource.RLIMIT_THREADS

   各プロセスが作成できるスレッド数の上限です。

   利用可能な環境: AIX.

   Added in version 3.15.

resource.RLIMIT_UMTXP

   ユーザー ID ごとに割り当てられる、プロセス間で共有する POSIX スレッ
   ドライブラリのオブジェクト数の制限です。

   利用可能な環境: FreeBSD >= 11.

   Added in version 3.15.


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

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

resource.getrusage(who)

   *who* 引数の指定に従い、現在のプロセスまたはその子プロセスが消費し
   たリソースを表すオブジェクトを返します。 *who* 引数には、以下で説明
   する "RUSAGE_*" 定数のいずれかを指定してください。

   簡単な例:

      from resource import *
      import time

      # CPU に処理速度が制約されないタスク
      time.sleep(3)
      print(getrusage(RUSAGE_SELF))

      # CPU に処理速度が制約されるタスク
      for i in range(10 ** 8):
         _ = 1 + 1
      print(getrusage(RUSAGE_SELF))

   戻り値の各フィールドは、ユーザーモードで実行した時間や主記憶からプ
   ロセスがスワップアウトされた回数など、特定のシステムリソースの使用
   状況を表します。 プロセスのメモリ使用量など、一部の値はクロックの刻
   み幅に依存します。

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

   戻り値の "ru_utime" フィールドと "ru_stime" フィールドは、それぞれ
   ユーザーモードとシステムモードでの実行時間を表す浮動小数点数です。
   他の値は整数です。 各値の詳細は *getrusage(2)* マニュアルページを参
   照してください。 以下に概要を示します。

   +----------+------------------------+-----------------------------------------+
   | インデッ | フィールド             | リソース                                |
   | クス     |                        |                                         |
   |==========|========================|=========================================|
   | "0"      | "ru_utime"             | ユーザーモードでの時間 (浮動小数点数、  |
   |          |                        | 秒単位)                                 |
   +----------+------------------------+-----------------------------------------+
   | "1"      | "ru_stime"             | システムモードでの時間 (浮動小数点数、  |
   |          |                        | 秒単位)                                 |
   +----------+------------------------+-----------------------------------------+
   | "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()" に渡すと、呼び出し元プロセスの子プロセスのうち、終了
   して wait による回収も済んだものが消費したリソースを取得できます。

resource.RUSAGE_BOTH

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

resource.RUSAGE_THREAD

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

   Added in version 3.2.
