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.