"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)

   Sets new limits of consumption of *resource*. The *limits* argument
   must be a tuple "(soft, hard)" of two integers describing the new
   limits. A value of "RLIM_INFINITY" can be used to request a limit
   that is unlimited.

   Raises "ValueError" if an invalid resource is specified, if the new
   soft limit exceeds the hard limit, or if a process tries to raise
   its hard limit. Specifying a limit of "RLIM_INFINITY" when the hard
   or system limit for that resource is not unlimited will result in a
   "ValueError".  A process with the effective UID of super-user can
   request any valid limit value, including unlimited, but
   "ValueError" will still be raised if the requested limit exceeds
   the system imposed limit.

   "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

   The maximum amount of processor time (in seconds) that a process
   can use. If this limit is exceeded, a "SIGXCPU" signal is sent to
   the process. (See the "signal" module documentation for information
   about how to catch this signal and do something useful, e.g. flush
   open files to disk.)

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

   The largest area of mapped memory which the process may occupy.
   Usually an alias of "RLIMIT_AS".

   Availability: Solaris, FreeBSD, NetBSD.

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, NetBSD.

   Added in version 3.4.

resource.RLIMIT_SWAP

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

   Availability: FreeBSD >= 8.

   Added in version 3.4.

resource.RLIMIT_NPTS

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

   Availability: FreeBSD >= 8.

   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))

   The fields of the return value each describe how a particular
   system resource has been used, e.g. amount of time spent running in
   user mode or number of times the process was swapped out of main
   memory. Some values are dependent on the clock tick interval, e.g.
   the amount of memory the process is using.

   以前のバージョンとの互換性のため、返される値は 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.
