"resource" --- 资源使用信息
***************************

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

该模块提供了测量和控制程序所利用的系统资源的基本机制。

适用范围: Unix, not WASI.

符号常量被用来指定特定的系统资源，并要求获得关于当前进程或其子进程的使
用信息。

当系统调用失败时，会触发一个 "OSError"。

exception resource.error

   一个被弃用的 "OSError" 的别名。

   在 3.3 版本发生变更: 根据 **PEP 3151**，这个类是 "OSError" 的别名。


资源限制
========

资源的使用可以通过下面描述的 "setrlimit()" 函数来限制。每个资源都被一
对限制所控制：一个软限制和一个硬限制。软限制是当前的限制，并且可以由一
个进程随着时间的推移而降低或提高。软限制永远不能超过硬限制。硬限制可以
降低到大于软限制的任何数值，但不能提高。（只有拥有超级用户有效 UID 的
进程才能提高硬限制。)

可以被限制的具体资源取决于系统。它们在 man *getrlimit(2)* 中描述。 下
面列出的资源在底层操作系统支持的情况下被支持；那些不能被操作系统检查或
控制的资源在本模块中没有为这些平台定义。

resource.RLIM_INFINITY

   用于表示资源无限制的常量。

resource.getrlimit(resource)

   返回一个包含 *resource* 当前软限制和硬限制的元组。如果指定了一个无
   效的资源，则触发 "ValueError" ，如果底层系统调用意外失败，则引发
   "error"。

resource.setrlimit(resource, limits)

   设置新的 *resource* 消耗限制。 *limits* 参数必须为一个由描述新限制
   的两个整数组成的元组 "(soft, hard)"。 "RLIM_INFINITY" 值可被用来请
   求设为无限制。

   如果指定了一个无效的资源，如果新的软限制超过了硬限制，或者如果一个
   进程试图提高它的硬限制，将会引发 "ValueError"。 在资源的硬限制或系
   统限制不是无限时指定 "RLIM_INFINITY" 限制将导致 "ValueError"。一个
   有效 UID 为超级用户的进程可以请求任何有效的限制值，包括无限，但如果
   请求的限制超过了系统设定的限制仍然会引发 "ValueError"。

   如果底层系统调用失败，"setrlimit" 也可能触发 "error"。

   VxWorks 只支持设置 "RLIMIT_NOFILE"。

   引发一个 审计事件 "resource.setrlimit" 并附带参数 "resource",
   "limits".

resource.prlimit(pid, resource[, limits])

   将 "setrlimit()" 和 "getrlimit()" 合并为一个函数，支持获取和设置任
   意进程的资源限制。如果 *pid* 为 0，那么该调用适用于当前进程。
   *resource* 和 *limits* 的含义与 "setrlimit()" 相同，只是 *limits*
   是可选的。

   当 *limits* 没有给出时，该函数返回进程 *pid* 的 *resource* 限制。当
   *limits* 被给定时，进程的 *resource* 限制被设置，并返回以前的资源限
   制。

   当 *pid* 找不到时，触发 "ProcessLookupError"；当用户没有进程的
   "CAP_SYS_RESOURCE" 时，触发 "PermissionError"。

   引发一个 审计事件 "resource.prlimit" 并附带参数 "pid", "resource",
   "limits".

   适用范围: Linux >= 2.6.36 with glibc >= 2.13.

   Added in version 3.4.

这些符号定义了资源的消耗可以通过下面描述的 "setrlimit()" 和
"getrlimit()" 函数来控制。这些符号的值正是 C 程序所使用的常数。

Unix man 页面 *getrlimit(2)* 列出了可用的资源。注意，并非所有系统都使
用相同的符号或相同的值来表示相同的资源。本模块并不试图掩盖平台的差异——
没有为某一平台定义的符号在该平台上将无法从本模块中获得。

resource.RLIMIT_CORE

   当前进程可以创建的核心文件的最大大小（以字节为单位）。如果需要更大
   的核心文件来包含整个进程的镜像，这可能会导致创建一个部分核心文件。

resource.RLIMIT_CPU

   一个进程可以使用的最大处理器时间（以秒为单位）。如果超过此限制，将
   向进程发送 "SIGXCPU" 信号。 （请参阅 "signal" 模块文档了解如何捕捉
   此信号并做一些有用的事情，例如将打开的文件数据刷新到磁盘。）

resource.RLIMIT_FSIZE

   进程可能创建的文件的最大大小。

resource.RLIMIT_DATA

   进程的堆的最大大小（以字节为单位）。

resource.RLIMIT_STACK

   当前进程的调用堆栈的最大大小（字节）。这只影响到多线程进程中主线程
   的堆栈。

resource.RLIMIT_RSS

   应该提供给进程的最大常驻内存大小。

resource.RLIMIT_NPROC

   当前进程可能创建的最大进程数。

resource.RLIMIT_NOFILE

   当前进程打开的文件描述符的最大数量。

resource.RLIMIT_OFILE

   BSD 对 "RLIMIT_NOFILE" 的命名。

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

   这个用户使用的套接字缓冲区的最大大小（字节数）。这限制了这个用户在
   任何时候都可以持有的网络内存数量，因此也限制了 mbufs 的数量。

   适用范围: FreeBSD, NetBSD.

   Added in version 3.4.

resource.RLIMIT_SWAP

   这个用户 ID 的所有进程可能保留或使用的交换空间的大小上限（以字节数
   表示）。此限制只有在 vm.overcommit sysctl 的 1 号比特位被设置时才会
   生效。请参阅 tuning(7) 获取该 sysctl 的完整描述。

   适用范围: 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.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))

   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 个元素的元组来访问。

   返回值中的 "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"             | swap out 的数量                         |
   +----------+------------------------+-----------------------------------------+
   | "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()" 以请求当前线程所消耗的资源。并非所有系统都能使
   用。

   Added in version 3.2.
