# `resource` — Resource usage information

Цей модуль надає базові механізми для вимірювання та контролю системних ресурсів, що використовуються програмою.

Availability: Unix, not WASI.

Символьні константи використовуються для вказівки певних системних ресурсів і запиту інформації про використання поточного процесу або його дочірніх процесів.

У разі помилки системного виклику виникає `OSError`.

exception resource.error

  Застарілий псевдонім `OSError`.

  Змінено в версії 3.3: Після PEP 3151 цей клас отримав псевдонім `OSError`.

## Обмеження ресурсів

Використання ресурсів можна обмежити за допомогою функції `setrlimit()`, описаної нижче. Кожен ресурс контролюється парою обмежень: м’яким обмеженням і жорстким обмеженням. М’яке обмеження – це поточне обмеження, яке з часом може бути знижено або підвищено процесом. М’яке обмеження ніколи не може перевищувати жорстке обмеження. Жорстке обмеження можна знизити до будь-якого значення, що перевищує м’яке обмеження, але не підняти. (Тільки процеси з ефективним UID суперкористувача можуть підняти жорстке обмеження.)

Конкретні ресурси, які можна обмежити, залежать від системи. Вони описані на сторінці довідки getrlimit(2). Перелічені нижче ресурси підтримуються, якщо їх підтримує базова операційна система; ресурси, які не можуть бути перевірені або контрольовані операційною системою, не визначені в цьому модулі для цих платформ.

resource.RLIM_INFINITY

  Константа, яка використовується для позначення обмеження для необмеженого ресурсу.

  Змінено в версії 3.15.0a0 (unreleased): It is now always positive. Previously, it could be negative, such as -1 or -3.

resource.RLIM_SAVED_CUR

resource.RLIM_SAVED_MAX

  Constants used to represent the soft and hard limit values if they cannot be represented in the `rlim_t` value in C. Can be equal to `RLIM_INFINITY`.

  Added in version 3.15.0a0 (unreleased).

resource.getrlimit(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`.

  Викликає подію аудиту `resource.setrlimit` з аргументами `resource`, `limits`.

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

  Поєднує `setrlimit()` і `getrlimit()` в одній функції та підтримує отримання та встановлення обмежень ресурсів довільного процесу. Якщо pid дорівнює 0, тоді виклик застосовується до поточного процесу. resource і limits мають те саме значення, що й у `setrlimit()`, за винятком того, що limits є необов’язковим.

  Якщо limits не задано, функція повертає обмеження resource процесу pid. Коли задано limits, встановлюється обмеження resource для процесу та повертається попередній ліміт ресурсів.

  Викликає `ProcessLookupError`, коли pid не може бути знайдено, і `PermissionError`, коли користувач не має `CAP_SYS_RESOURCE` для процесу.

  Викликає подію аудиту `resource.prlimit` з аргументами `pid`, `resource`, `limits`.

  Availability: Linux >= 2.6.36 with glibc >= 2.13.

  Added in version 3.4.

Ці символи визначають ресурси, споживання яких можна контролювати за допомогою функцій `setrlimit()` і `getrlimit()`, описаних нижче. Значення цих символів точно є константами, які використовуються програмами на Сі.

Сторінка довідки Unix для 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

  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

  Стеля для хорошого рівня процесу (розраховується як 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

  Обмеження часу (у мікросекундах) процесорного часу, який процес може витрачати в режимі планування в реальному часі без виконання блокуючого системного виклику.

  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

  The maximum size (in bytes) of the swap space that may be reserved or used by all of this user id’s processes. This limit is enforced only if bit 1 of the vm.overcommit sysctl is set. Please see tuning(7) for a complete description of this sysctl.

  Availability: FreeBSD >= 8.

  Added in version 3.4.

resource.RLIMIT_NPTS

  Максимальна кількість псевдотерміналів, створених цим ідентифікатором користувача.

  Availability: FreeBSD >= 8.

  Added in version 3.4.

resource.RLIMIT_KQUEUES

  Максимальна кількість kqueue, яку дозволено створити цьому ідентифікатору користувача.

  Availability: FreeBSD >= 11.

  Added in version 3.10.

resource.RLIMIT_NTHR

  The maximum number of threads for this user id, not counting the main and kernel threads.

  Availability: NetBSD >= 7.0.

  Added in version 3.15.0a0 (unreleased).

resource.RLIMIT_PIPEBUF

  The maximum total size of in-kernel buffers for bi-directional pipes/fifos that this user id is allowed to consume.

  Availability: FreeBSD >= 14.2.

  Added in version 3.15.0a0 (unreleased).

resource.RLIMIT_THREADS

  The maximum number of threads each process can create.

  Availability: AIX.

  Added in version 3.15.0a0 (unreleased).

resource.RLIMIT_UMTXP

  The limit of the number of process-shared Posix thread library objects allocated by user id.

  Availability: FreeBSD >= 11.

  Added in version 3.15.0a0 (unreleased).

## Використання ресурсів

Ці функції використовуються для отримання інформації про використання ресурсів:

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

  Кожне з полів поверненого значення описує, як використовувався певний системний ресурс, напр. кількість часу, витраченого на роботу, є режимом користувача або кількістю разів, коли процес вивантажувався з основної пам’яті. Деякі значення залежать від внутрішнього такту годинника, напр. обсяг пам’яті, який використовує процес.

  Для зворотної сумісності повернуте значення також доступне як кортеж із 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` | час у режимі користувача (секунд з плаваючою точкою)
  `1` | `ru_stime` | час у системному режимі (секунд з плаваючою точкою)
  `2` | `ru_maxrss` | максимальний розмір резидентного набору
  `3` | `ru_ixrss` | розмір спільної пам’яті
  `4` | `ru_idrss` | нерозділений розмір пам’яті
  `5` | `ru_isrss` | розмір стеку без спільного доступу
  `6` | `ru_minflt` | помилки сторінки, які не вимагають введення-виведення
  `7` | `ru_majflt` | помилки сторінки, які вимагають введення-виведення
  `8` | `ru_nswap` | кількість обмінів
  `9` | `ru_inblock` | операції введення блоку
  `10` | `ru_oublock` | операції виведення блоків
  `11` | `ru_msgsnd` | надісланих повідомлень
  `12` | `ru_msgrcv` | отриманих повідомлень
  `13` | `ru_nsignals` | отримані сигнали
  `14` | `ru_nvcsw` | добровільні перемикання контексту
  `15` | `ru_nivcsw` | мимовільні перемикання контексту

  Ця функція викличе `ValueError`, якщо вказано недійсний параметр who. Він також може викликати виняток `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.