# `resource` — Resource usage information

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

Availability: Unix, not Emscripten, not WASI.

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

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

exception resource.error

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

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

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

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

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

resource.RLIM_INFINITY

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

resource.getrlimit(resource)

  Повертає кортеж `(soft, hard)` із поточними м’якими та жорсткими обмеженнями ресурсу. Викликає `ValueError`, якщо вказано недійсний ресурс, або `error`, якщо основний системний виклик несподівано завершується помилкою.

resource.setrlimit(resource, limits)

  Встановлює нові обмеження споживання ресурсу. Аргумент 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 не задано, функція повертає обмеження resource процесу pid. Коли задано limits, встановлюється обмеження resource для процесу та повертається попередній ліміт ресурсів.

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

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

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

  Нове в версії 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

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

  Availability: FreeBSD >= 11.

resource.RLIMIT_AS

  Максимальна площа (у байтах) адресного простору, яку може зайняти процес.

resource.RLIMIT_MSGQUEUE

  Кількість байтів, які можна виділити для черг повідомлень POSIX.

  Availability: Linux >= 2.6.8.

  Нове в версії 3.4.

resource.RLIMIT_NICE

  Стеля для хорошого рівня процесу (розраховується як 20 - rlim_cur).

  Availability: Linux >= 2.6.12.

  Нове в версії 3.4.

resource.RLIMIT_RTPRIO

  Стеля пріоритету в реальному часі.

  Availability: Linux >= 2.6.12.

  Нове в версії 3.4.

resource.RLIMIT_RTTIME

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

  Availability: Linux >= 2.6.25.

  Нове в версії 3.4.

resource.RLIMIT_SIGPENDING

  Кількість сигналів, які процес може поставити в чергу.

  Availability: Linux >= 2.6.8.

  Нове в версії 3.4.

resource.RLIMIT_SBSIZE

  Максимальний розмір (у байтах) використання буфера сокета для цього користувача. Це обмежує обсяг мережевої пам’яті, а отже, і кількість mbuf, які цей користувач може зберігати в будь-який час.

  Availability: FreeBSD.

  Нове в версії 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.

  Нове в версії 3.4.

resource.RLIMIT_NPTS

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

  Availability: FreeBSD.

  Нове в версії 3.4.

resource.RLIMIT_KQUEUES

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

  Availability: FreeBSD >= 11.

  Нове в версії 3.10.

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

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

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()`, щоб запитати ресурси, спожиті поточним потоком. Може бути недоступний у всіх системах.

  Нове в версії 3.2.