"_thread" --- API de bajo nivel para manejo de hilos
****************************************************

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

Este módulo ofrece primitivas de bajo nivel para trabajar con
múltiples *threads* o hilos (también llamados *light-weight processes*
o *tasks*) -- múltiples hilos de control compartiendo su espacio de
datos global. Para sincronizar, provee "candados" simples (también
llamados  *mutexes* o *binary semaphores*). El módulo "threading"
provee una API de manejo de hilos más fácil de usar y de más alto
nivel, construida sobre este módulo.

Distinto en la versión 3.7: Este módulo solía ser opcional, pero ahora
está siempre disponible.

Este módulo define las siguientes constantes y funciones:

exception _thread.error

   Lanzado ante errores específicos de un hilo.

   Distinto en la versión 3.3: Ahora es un sinónimo de la excepción
   incorporada "RuntimeError".

_thread.LockType

   Este es el tipo de los objetos candado (*lock objects*).

_thread.start_new_thread(function, args[, kwargs])

   Inicia un nuevo hilo y retorna su identificador. El hilo ejecuta la
   función *function* con la lista de argumentos *args* (que debe ser
   una tupla). El argumento opcional *kwargs* especifica un
   diccionario de argumentos por palabras clave.

   Cuando la función retorna, el hilo finaliza silenciosamente.

   Cuando la función termina con una excepción no gestionada, se
   invoca a "sys.unraisablehook()" para que gestione la excepción. El
   atributo *object* del argumento gancho (*hook*), es *function*. Por
   defecto, se muestra un seguimiento de pila y luego el hilo sale
   (pero los otros hilos continúan funcionando).

   Cuando la función lanza una excepción "SystemExit", se ignora
   silenciosamente.

   Distinto en la versión 3.8: Ahora se utiliza "sys.unraisablehook()"
   para gestionar las excepciones no gestionadas.

_thread.interrupt_main()

   Simular el efecto de una señal "signal.SIGINT" que llega al hilo
   principal. Un hilo puede usar esta función para interrumpir el hilo
   principal.

   Si "signal.SIGINT" no está gestionada por Python (se definió
   "signal.SIG_DFL" o "signal.SIG_IGN"), esta función no hace nada.

_thread.exit()

   Lanza la excepción "SystemExit". Cuando no es gestionada, causa que
   el hilo salga silenciosamente.

_thread.allocate_lock()

   Retorna un nuevo objeto candado (*lock object*). Los métodos de los
   candados se describen más abajo. El candado está abierto al inicio.

_thread.get_ident()

   Retorna el 'identificador de hilo' (*thread identifier*) del hilo
   actual. Es un entero distinto de cero. Su valor no tiene un
   significado directo, tiene la intención de ser utilizada como una
   *cookie* mágica para, por ejemplo, indexar un diccionario con datos
   específicos del hilo. Los identificadores de hilo pueden reciclarse
   cuando un hilo sale y otro se crea.

_thread.get_native_id()

   Retorna el ID de hilo nativo integral del hilo asignado por el
   kernel. Es un entero no-negativo. Su valor puede utilizarse para
   identificar inequívocamente este hilo en particular en todo el
   sistema (hasta que el hilo termine, luego de lo cual el valor puede
   ser reciclado por el Sistema Operativo).

   Disponibilidad: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD,
   AIX.

   Nuevo en la versión 3.8.

_thread.stack_size([size])

   Retorna el tamaño de la pila del hilo (*thread stack*) utilizada al
   crear nuevos hilos. El argumento opcional *size* especifica el
   tamaño de la pila a utilizar en los hilos que se creen a
   continuación, y debe ser 0 (utiliza el valor por defecto de la
   plataforma o el configurado) o un entero positivo de al menos 32768
   (32KiB). Si *size* no se especifica, se utiliza 0. Si no está
   soportado el cambio del tamaño de pila del hilo, se lanza una
   excepción "RuntimeError". Si la pila especificada es inválida se
   lanza un "ValueError" y el tamaño de la pila no se modifica. 32KiB
   es actualmente el menor valor soportado para el tamaño de la pila,
   para garantizar suficiente espacio en la misma para que quepa el
   propio intérprete. Tenga en cuenta que alguna plataformas pueden
   tener restricciones particulares en los valores para el tamaño de
   la pila, como requerir un mínimo que supere los 32KiB, o requerir
   una asignación en múltiplos del tamaño de página de memoria del
   sistema. Es necesario consultar la documentación de la plataforma
   para mayor información (son habituales las páginas de 4KiB; usar
   múltiplos de 4096 para el tamaño de pila es la estrategia sugerida
   si no se cuenta con información más específica).

   Disponibilidad: Sistemas Windows, con hilos POSIX.

_thread.TIMEOUT_MAX

   El máximo valor permitido para el parámetro *timeout* de
   "Lock.acquire()". Especificar un tiempo de espera (*timeout*) mayor
   que este valor lanzará una excepción "OverflowError".

   Nuevo en la versión 3.2.

Los objetos candado (*lock objects*) tienen los siguientes métodos:

lock.acquire(waitflag=1, timeout=-1)

   Sin ningún argumento opcional, este método adquiere el candado
   incondicionalmente, si es necesario esperando que éste sea liberado
   por otro hilo (solamente un hilo por vez puede adquirir un candado;
   para eso existen).

   Si el argumento entero *waitflag* está presente, la acción depende
   de su valor: si es cero, el candado solamente es adquirido si está
   disponible de forma inmediata, sin esperas. Mientras que si es
   distinto de cero, el candado es adquirido sin condiciones, como en
   el caso anterior.

   Si el argumento de punto flotante *timeout* está presente y es
   positivo, especifica el tiempo máximo de espera en segundos antes
   de retornar. Un argumento *timeout* negativo, especifica una espera
   ilimitada. No se puede especificar un *timeout* si *waitflag* es
   cero.

   El valor de retorno es "True" si el candado (*lock*) se adquirió
   exitosamente, "False" de lo contrario.

   Distinto en la versión 3.2: El parámetro *timeout* es nuevo.

   Distinto en la versión 3.2: La adquisición de candados ahora puede
   ser interrumpida por señales en POSIX.

lock.release()

   Libera el candado. El candado debe haber sido adquirido
   previamente, pero no necesariamente por el mismo hilo.

lock.locked()

   Retorna el estado del candado: "True" si ha sido adquirido por
   algún hilo, "False" de lo contrario.

Además de estos métodos, los objetos candado pueden ser utilizados
mediante la declaración "with", por ejemplo:

   import _thread

   a_lock = _thread.allocate_lock()

   with a_lock:
       print("a_lock is locked while this executes")

**Salvedades:**

* Los hilos interactúan de manera extraña con interrupciones: la
  excepción "KeyboardInterrupt" va a ser recibida por un hilo
  cualquiera. (Cuando el módulo "signal" está disponible, la
  interrupción siempre se dirige al hilo principal.

* Invocar a "sys.exit()" o lanzar la excepción "SystemExit" equivale a
  invocar "_thread.exit()".

* No es posible interrumpir el método "acquire()" en un candado. La
  excepción "KeyboardInterrupt" tendrá lugar después de que el candado
  haya sido adquirido.

* Cuando el hilo principal sale, ¿sobreviven los otros hilos? Depende
  de cómo esté definido por el sistema. En la mayoría de los sistemas,
  los hilos se cierran inmediatamente (*killed*), sin ejecutar las
  cláusulas "try" ... "finally" o los destructores del objeto.

* Cuando el hilo principal sale, no hace ninguna de las tareas de
  limpieza habituales (excepto que se haga honor a las cláusulas "try"
  ... "finally"), y los archivos de E/S estándar no son liberados.
