"resource" --- Información sobre el uso de recursos
***************************************************

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

Este módulo proporciona mecanismos básicos para medir y controlar los
recursos del sistema utilizados por un programa.

Las constantes simbólicas se utilizan para especificar recursos
concretos del sistema y para solicitar información de uso sobre el
proceso actual o sus elementos secundarios.

Se genera un "OSError" cuando la llamada al sistema (*syscall*) falla.

exception resource.error

   Un alias en desuso de "OSError".

   Distinto en la versión 3.3: Tras **PEP 3151** esta clase se
   convirtió en un alias de "OSError".


Límites de recursos
===================

El uso de recursos se puede limitar usando la función "setrlimit()"
que se describe a continuación. Cada recurso está controlado por un
par de límites: un límite flexible y un límite duro. El límite
flexible es el límite actual, y puede ser reducido o elevado con el
tiempo mediante un proceso. El límite flexible nunca puede exceder el
límite duro. El límite duro se puede reducir a cualquier valor mayor
que el del límite flexible, pero no se puede elevar. (Solo los
procesos con el UID efectivo del superusuario pueden aumentar un
límite duro.)

Los recursos específicos que se pueden limitar dependen del sistema.
Se describen en la página de manual *getrlimit(2)*. Los recursos
enumerados a continuación se admiten cuando el sistema operativo
subyacente los admite; los recursos que no pueden ser verificados o
controlados por el sistema operativo no se definen en este módulo para
esas plataformas.

resource.RLIM_INFINITY

   Constante utilizada para representar el límite de un recurso
   ilimitado.

resource.getrlimit(resource)

   Retorna una tupla "(soft, hard)" con los límites flexible y duro
   actuales de *resource*. Genera "ValueError" si se especifica un
   recurso no válido o "error" si la llamada al sistema subyacente
   falla inesperadamente.

resource.setrlimit(resource, limits)

   Establece nuevos límites para el consumo de *resource*. El
   argumento *limits* debe ser una tupla de dos enteros "(soft, hard)"
   que describe los nuevos límites. Un valor de "RLIM_INFINITY" se
   puede utilizar para solicitar un límite ilimitado.

   Genera "ValueError" si se especifica un recurso no válido, si el
   nuevo límite flexible excede el límite duro, o si un proceso
   intenta aumentar el límite duro. Si se especifica un límite de
   "RLIM_INFINITY" cuando el límite duro o el límite del sistema para
   ese recurso no son ilimitados, se producirá un "ValueError". Un
   proceso con el UID efectivo de superusuario puede solicitar
   cualquier valor de límite válido, incluso ilimitado, pero se
   lanzará un "ValueError" si el límite solicitado excede el límite
   impuesto por el sistema.

   "setrlimit" también puede generar un "error" si falla la llamada al
   sistema subyacente.

   VxWorks solo admite configurar "RLIMIT_NOFILE".

   Genera un auditing event "resource.setrlimit" con los argumentos
   "resource", "limits".

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

   Combina "setrlimit()" y "getrlimit()" en una sola función y admite
   obtener y establecer los límites de recursos de un proceso
   arbitrario. Si *pid* es 0, entonces la llamada se aplica al proceso
   actual. *resource* y *limits* tienen el mismo significado que en
   "setrlimit()", excepto por que *limits* es opcional.

   Cuando no se proporciona *limits* la función retorna el límite de
   *resource* del proceso *pid*. Cuando se proporciona *limits*, se
   establece el límite de *resource* del proceso y se retorna el
   límite de recursos anterior.

   Genera "ProcessLookupError" cuando no se encuentra *pid* y
   "PermissionError" cuando el usuario no tiene "CAP_SYS_RESOURCE"
   para el proceso.

   Genera un evento de auditoría "resource.prlimit" con los argumentos
   "pid", "resource", "limits".

   Disponibilidad: Linux 2.6.36 o posterior con glibc 2.13 o
   posterior.

   Nuevo en la versión 3.4.

Estos símbolos definen los recursos cuyo consumo se puede controlar
usando las funciones "setrlimit()" y "getrlimit()" que se describen
más abajo. Los valores de estos símbolos son exactamente las
constantes utilizadas por programas en C.

La página de manual de Unix para *getrlimit(2)* detalla los recursos
disponibles. Tenga en cuenta que no todos los sistemas usan el mismo
símbolo o el mismo valor para referirse al mismo recurso. Este módulo
no pretende enmascarar las diferencias entre plataformas --- los
símbolos no definidos para una plataforma no estarán disponibles en
este módulo en esa plataforma.

resource.RLIMIT_CORE

   El tamaño máximo (en bytes) de un archivo central que puede crear
   el proceso actual. Esto podría resultar en la creación de un
   archivo central parcial si se requiriera uno más grande para
   contener la imagen del proceso entera.

resource.RLIMIT_CPU

   La cantidad máxima de tiempo del procesador (en segundos) que puede
   utilizar un proceso. Si se excede este límite se envía una señal
   "SIGXCPU" al proceso. (Vea la documentación del módulo "signal"
   para más información sobre cómo detectar esta señal y hacer algo
   productivo, p. ej. descargar los archivos abiertos al disco).

resource.RLIMIT_FSIZE

   El tamaño máximo de un archivo que pueda crear el proceso.

resource.RLIMIT_DATA

   El tamaño máximo (en bytes) de la memoria *heap* del proceso.

resource.RLIMIT_STACK

   El tamaño máximo (en bytes) de la pila de llamadas para el proceso
   actual. Esto afecta únicamente a la pila del hilo principal en un
   proceso multi-hilo.

resource.RLIMIT_RSS

   El tamaño máximo del conjunto residente (*RSS*) del que puede
   disponer el proceso.

resource.RLIMIT_NPROC

   El número máximo de procesos que puede crear el proceso actual.

resource.RLIMIT_NOFILE

   El número máximo de descriptores de archivo abierto para el proceso
   actual.

resource.RLIMIT_OFILE

   El nombre BDS para "RLIMIT_NOFILE".

resource.RLIMIT_MEMLOCK

   El espacio de direcciones máximo que se puede bloquear en la
   memoria.

resource.RLIMIT_VMEM

   El área de memoria mapeada más grande que puede ocupar el proceso.

resource.RLIMIT_AS

   El área máxima (en bytes) de espacio de direcciones que puede tomar
   el proceso.

resource.RLIMIT_MSGQUEUE

   El número de bytes que se pueden asignar a las colas de mensajes
   POSIX.

   Disponibilidad: Linux 2.6.8 o posterior.

   Nuevo en la versión 3.4.

resource.RLIMIT_NICE

   El techo del nivel del proceso *nice* (calculado como 20 -
   rlim_cur).

   Disponibilidad: Linux 2.6.12 o posterior.

   Nuevo en la versión 3.4.

resource.RLIMIT_RTPRIO

   El techo de la prioridad en tiempo real.

   Disponibilidad: Linux 2.6.12 o posterior.

   Nuevo en la versión 3.4.

resource.RLIMIT_RTTIME

   El límite de tiempo (en microsegundos) en tiempo de CPU que puede
   dedicar un proceso de programación en tiempo real sin hacer una
   llamada al sistema de bloqueo.

   Disponibilidad: Linux 2.6.25 o posterior.

   Nuevo en la versión 3.4.

resource.RLIMIT_SIGPENDING

   El número de señales que el proceso puede poner en cola.

   Disponibilidad: Linux 2.6.8 o posterior.

   Nuevo en la versión 3.4.

resource.RLIMIT_SBSIZE

   El tamaño máximo (en bytes) de uso del búfer del socket para este
   usuario. Esto limita la cantidad de memoria de red, y por lo tanto
   la cantidad de mbufs, que este usuario puede retener en todo
   momento.

   Disponibilidad: FreeBSD 9 o posterior.

   Nuevo en la versión 3.4.

resource.RLIMIT_SWAP

   El tamaño máximo (en bytes) del espacio de intercambio que puede
   ser reservado o utilizado por todos los procesos de este ID de
   usuario. Este límite se aplica solo si se establece el bit 1 de
   vm.overcommit sysctl. Consulte tuning(7) para obtener una
   descripción completa de este sysctl.

   Disponibilidad: FreeBSD 9 o posterior.

   Nuevo en la versión 3.4.

resource.RLIMIT_NPTS

   El número máximo de pseudo-terminales que puede crear esta ID de
   usuario.

   Disponibilidad: FreeBSD 9 o posterior.

   Nuevo en la versión 3.4.

resource.RLIMIT_KQUEUES

   El número máximo de kqueues que este ID de usuario puede crear.

   Disponibilidad: FreeBSD 11 o posterior.

   Nuevo en la versión 3.10.


Utilización de recursos
=======================

Estas funciones se usan para recuperar la información de utilización
de recursos:

resource.getrusage(who)

   Esta función retorna un objeto que describe los recursos consumidos
   por el proceso actual o sus elementos secundarios, según como esté
   especificado en el parámetro *who*. El parámetro *who* debe
   especificarse usando una de las constantes "RUSAGE_*" descritas más
   abajo.

   Un ejemplo sencillo:

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

   Los campos del valor retornado describen cómo se ha utilizado un
   recurso específico, p. ej. la cantidad de tiempo dedicada a la
   ejecución en modo usuario o el número de veces que el proceso ha
   sido intercambiado desde la memoria principal. Algunos valores
   dependen del intervalo de tic del reloj, p. ej. la cantidad de
   memoria que está usando el proceso.

   Por compatibilidad con versiones anteriores, el valor retornado es
   accesible también como una tupla de 16 elementos.

   Los campos "ru_utime" y "ru_stime" del valor retornado son valores
   de coma flotante que representan la cantidad de tiempo dedicada a
   la ejecución en modo usuario y la cantidad de tiempo dedicada a la
   ejecución en modo sistema respectivamente. Los valores restantes
   son enteros. Consulte la página del manual *getrusage(2)* para
   información detallada sobre estos valores. A continuación se
   presenta un breve resumen:

   +----------+-----------------------+-----------------------------------------+
   | Índice   | Campo                 | Recurso                                 |
   |==========|=======================|=========================================|
   | "0"      | "ru_utime"            | tiempo en modo usuario (flotante en     |
   |          |                       | segundos)                               |
   +----------+-----------------------+-----------------------------------------+
   | "1"      | "ru_stime"            | tiempo en modo sistema (flotante en     |
   |          |                       | segundos)                               |
   +----------+-----------------------+-----------------------------------------+
   | "2"      | "ru_maxrss"           | tamaño máximo del conjunto residente    |
   +----------+-----------------------+-----------------------------------------+
   | "3"      | "ru_ixrss"            | tamaño de memoria compartida            |
   +----------+-----------------------+-----------------------------------------+
   | "4"      | "ru_idrss"            | tamaño de memoria no compartida         |
   +----------+-----------------------+-----------------------------------------+
   | "5"      | "ru_isrss"            | tamaño de la pila no compartida         |
   +----------+-----------------------+-----------------------------------------+
   | "6"      | "ru_minflt"           | fallos de página que no requieran E/S   |
   +----------+-----------------------+-----------------------------------------+
   | "7"      | "ru_majflt"           | fallos de página que requieran E/S      |
   +----------+-----------------------+-----------------------------------------+
   | "8"      | "ru_nswap"            | número de intercambios                  |
   +----------+-----------------------+-----------------------------------------+
   | "9"      | "ru_inblock"          | bloque de operaciones de entrada        |
   +----------+-----------------------+-----------------------------------------+
   | "10"     | "ru_oublock"          | bloque de operaciones de salida         |
   +----------+-----------------------+-----------------------------------------+
   | "11"     | "ru_msgsnd"           | mensajes enviados                       |
   +----------+-----------------------+-----------------------------------------+
   | "12"     | "ru_msgrcv"           | mensajes recibidos                      |
   +----------+-----------------------+-----------------------------------------+
   | "13"     | "ru_nsignals"         | señales recibidas                       |
   +----------+-----------------------+-----------------------------------------+
   | "14"     | "ru_nvcsw"            | intercambios de contexto voluntarios    |
   +----------+-----------------------+-----------------------------------------+
   | "15"     | "ru_nivcsw"           | intercambios de contexto involuntarios  |
   +----------+-----------------------+-----------------------------------------+

   Esta función lanzará un "ValueError" si el parámetro *who*
   especificado no es válido. También puede generar una excepción
   "error" en circunstancias inusuales.

resource.getpagesize()

   Retorna el número de bytes en una página de sistema. (Esta no es
   necesariamente del mismo tamaño que la página de hardware).

Los siguientes símbolos "RUSAGE_*" se pasan a la función "getrusage()"
para especificar qué información de procesos se debería proporcionar.

resource.RUSAGE_SELF

   Pasar a "getrusage()" para solicitar recursos consumidos por el
   proceso de llamada, que es la suma de recursos utilizados por todos
   los hilos en el proceso.

resource.RUSAGE_CHILDREN

   Pasar a "getrusage()" para solicitar recursos consumidos por
   procesos secundarios del proceso de llamada que se han terminado o
   a los que se les está esperando.

resource.RUSAGE_BOTH

   Pasar a "getrusage()" para solicitar recursos consumidos por el
   proceso actual y sus procesos secundarios. Puede que no esté
   disponible en todos los sistemas.

resource.RUSAGE_THREAD

   Pasa a "getrusage()" para solicitar recursos consumidos por el hilo
   actual. Puede que no esté disponible en todos los sistemas.

   Nuevo en la versión 3.2.
