
:mod:`resource` --- リソース使用状態の情報
==========================================

.. module:: resource
   :platform: Unix
   :synopsis: 現プロセスのリソース使用状態を提供するためのインタフェース。
.. moduleauthor:: Jeremy Hylton <jeremy@alum.mit.edu>
.. sectionauthor:: Jeremy Hylton <jeremy@alum.mit.edu>


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

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

エラーを表すための例外が一つ定義されています:


.. exception:: error

   下に述べる関数は、背後にあるシステムコールが予期せず失敗した場合、このエラーを送出するかもしれません。


リソースの制限
--------------

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

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


.. function:: getrlimit(resource)

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


.. function:: setrlimit(resource, limits)

   *resouce* の新たな消費制限を設定します。
   *limits* 引数には、タプル ``(soft, hard)`` による二つの整数で、
   新たな制限を記述しなければなりません。
   現在指定可能な最大の制限を指定するために ``-1`` を使うことができます。

   無効なリソースが指定された場合、ソフトリミットの値がハードリミットの値を超えている場合、
   プロセスが (スーパユーザの有効な UID を持っていない状態で)
   ハードリミットを引き上げようとした場合には :exc:`ValueError` が送出されます。
   背後のシステムコールが予期せず失敗した場合には :exc:`error` が送出される可能性もあります。

以下のシンボルは、後に述べる関数 :func:`setrlimit` および :func:`getrlimit` を使って消費量を制御することができるリソース
を定義しています。これらのシンボルの値は、C プログラムで使われているシンボルと全く同じです。

:manpage:`getrlimit(2)` の Unix マニュアルページには、指定可能な
リソースが列挙されています。全てのシステムで同じシンボルが使われているわけではなく、また同じリソースを表すために同じ値が使われて
いるとも限らないので注意してください。このモジュールはプラットフォーム間の相違を隠蔽しようとはしていません --- あるプラットフォームで
定義されていないシンボルは、そのプラットフォーム向けの本モジュールでは利用することができません。


.. data:: RLIMIT_CORE

   現在のプロセスが生成できるコアファイルの最大 (バイト) サイズです。
   プロセスの全体イメージを入れるためにこの値より大きなサイズのコア
   ファイルが要求された結果、部分的なコアファイルが生成される可能性があります。


.. data:: RLIMIT_CPU

   プロセッサが利用することができる最大プロセッサ時間 (秒) です。
   この制限を超えた場合、 :const:`SIGXCPU` シグナルがプロセスに送られます。
   (どのようにしてシグナルを捕捉したり、例えば開かれているファイルをディスクにフラッシュするといった有用な処理を行うかについての情報は、
   :mod:`signal` モジュールのドキュメントを参照してください)


.. data:: RLIMIT_FSIZE

   プロセスが生成できるファイルの最大サイズです。マルチスレッドプロセスの場合、この値は主スレッドのスタックにのみ影響します。


.. data:: RLIMIT_DATA

   プロセスのヒープの最大 (バイト) サイズです。


.. data:: RLIMIT_STACK

   現在のプロセスのコールスタックの最大 (バイト) サイズです。


.. data:: RLIMIT_RSS

   プロセスが取りうる最大 RAM 常駐ページサイズ (resident set size) です。


.. data:: RLIMIT_NPROC

   現在のプロセスが生成できるプロセスの上限です。


.. data:: RLIMIT_NOFILE

   現在のプロセスが開けるファイル記述子の上限です。


.. data:: RLIMIT_OFILE

   :const:`RLIMIT_NOFILE` の BSD での名称です。


.. data:: RLIMIT_MEMLOCK

   メモリ中でロックできる最大アドレス空間です。


.. data:: RLIMIT_VMEM

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


.. data:: RLIMIT_AS

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


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

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


.. function:: getrusage(who)

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

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

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

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

   +------------+---------------------+--------------------------------------+
   | インデクス | フィールド名        | リソース                             |
   +============+=====================+======================================+
   | ``0``      | :attr:`ru_utime`    | ユーザモード実行時間 (float)         |
   +------------+---------------------+--------------------------------------+
   | ``1``      | :attr:`ru_stime`    | システムモード実行時間 (float)       |
   +------------+---------------------+--------------------------------------+
   | ``2``      | :attr:`ru_maxrss`   | 最大常駐ページサイズ                 |
   +------------+---------------------+--------------------------------------+
   | ``3``      | :attr:`ru_ixrss`    | 共有メモリサイズ                     |
   +------------+---------------------+--------------------------------------+
   | ``4``      | :attr:`ru_idrss`    | 非共有メモリサイズ                   |
   +------------+---------------------+--------------------------------------+
   | ``5``      | :attr:`ru_isrss`    | 非共有スタックサイズ                 |
   +------------+---------------------+--------------------------------------+
   | ``6``      | :attr:`ru_minflt`   | I/O を必要とするページフォールト数   |
   +------------+---------------------+--------------------------------------+
   | ``7``      | :attr:`ru_majflt`   | I/O を必要としないページフォールト数 |
   +------------+---------------------+--------------------------------------+
   | ``8``      | :attr:`ru_nswap`    | スワップアウト回数                   |
   +------------+---------------------+--------------------------------------+
   | ``9``      | :attr:`ru_inblock`  | ブロック入力操作数                   |
   +------------+---------------------+--------------------------------------+
   | ``10``     | :attr:`ru_oublock`  | ブロック出力操作数                   |
   +------------+---------------------+--------------------------------------+
   | ``11``     | :attr:`ru_msgsnd`   | 送信メッセージ数                     |
   +------------+---------------------+--------------------------------------+
   | ``12``     | :attr:`ru_msgrcv`   | 受信メッセージ数                     |
   +------------+---------------------+--------------------------------------+
   | ``13``     | :attr:`ru_nsignals` | 受信シグナル数                       |
   +------------+---------------------+--------------------------------------+
   | ``14``     | :attr:`ru_nvcsw`    | 自発的な実行コンテキスト切り替え数   |
   +------------+---------------------+--------------------------------------+
   | ``15``     | :attr:`ru_nivcsw`   | 非自発的な実行コンテキスト切り替え数 |
   +------------+---------------------+--------------------------------------+

   この関数は無効な *who* 引数を指定した場合には  :exc:`ValueError` を送出します。また、異常が発生した場合には
   :exc:`error` 例外が送出される可能性があります。

   .. versionchanged:: 2.3
      各値を返されたオブジェクトの属性としてアクセスできるようにしました.


.. function:: getpagesize()

   システムページ内のバイト数を返します。(ハードウェアページサイズと同じとは限りません。)
   この関数はプロセスが使用しているメモリのバイト数を決定する上で有効です。
   :func:`getrusage` が返すタプルの 3 つ目の要素はページ数で数えたメモリ使用量です;
   ページサイズを掛けるとバイト数になります。

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


.. data:: RUSAGE_SELF

   :const:`RUSAGE_SELF` はプロセス自体に属する情報を要求するために使われます。


.. data:: RUSAGE_CHILDREN

   :func:`getrusage` に渡すと呼び出し側プロセスの子プロセスのリソース情報を要求します。


.. data:: RUSAGE_BOTH

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

