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

   返回值的每个字段分别描述某一特定系统资源的使用情况，例如在用户模式
   下运行花费的时间或进程从主内存中被交换出的次数。 有些值取决于时钟周
   期，例如进程所使用的内存总量。

   为了向后兼容，返回值也可以作为一个 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.
