"_thread"--- API de segmentação de baixo nível
**********************************************

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

Este módulo fornece primitivos de baixo nível para trabalhar com
vários threads (também chamados *processos leves* ou *tarefas*) ---
vários threads de controle compartilhando seu espaço de dados global.
Para sincronização, travas simples (também chamadas de *mutexes*,
*exclusão mútua* ou *semáforos binários*) são fornecidas. O módulo
"threading" fornece uma API de segmentação mais fácil de usar e de
nível mais alto, construída sobre este módulo.

Alterado na versão 3.7: Este módulo costumava ser opcional, agora está
sempre disponível.

Este módulo define as seguintes constantes e funções:

exception _thread.error

   Gerado em erros específicos de segmento.

   Alterado na versão 3.3: Este é agora um sinônimo do componente
   embutido "RuntimeError".

_thread.LockType

   Este é o tipo de objetos de trava.

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

   Começa um novo tópico e retorna seu identificador. O tópico executa
   a função *function* com a lista de argumentos *args* (que deve ser
   uma tupla). O argumento opcional *kwargs* despecifica um dicionário
   de argumentos palavras-chave

   Quando a função retorna, o tópico fecha silenciosamente.

   Quando a função termina com uma exceção não processada,
   "sys.unraisablehook()" é chamada para lidar com a exceção. O
   atributo *object* do argumento do hook é *function*. Por padrão, um
   stack trace (situação da pilha de execução) é impresso e, em
   seguida, o thread sai (mas outros threads continuam a ser
   executados).

   Quando a função gera uma exceção "SystemExit", ela é ignorada.

   Levanta um evento de auditoria "_thread.start_new_thread" com os
   argumentos "function", "args", "kwargs".

   Alterado na versão 3.8: "sys.unraisablehook()" agora é usada para
   lidar com exceções não lidadas.

_thread.interrupt_main(signum=signal.SIGINT, /)

   Simule o efeito de um sinal chegando na thread principal. Uma
   thread pode usar esta função para interromper a thread principal,
   embora não haja garantia de que a interrupção ocorrerá
   imediatamente.

   Se fornecido, *signum* é o número do sinal a ser simulado. Se
   *signum* não for fornecido, "signal.SIGINT" será simulado.

   Se o sinal fornecido não for tratado por Python (foi definido como
   "signal.SIG_DFL" ou "signal.SIG_IGN"), esta função não faz nada.

   Alterado na versão 3.10: O argumento *signum* é adicionado para
   personalizar o sinal de número.

   Nota:

     Isso não emite o sinal correspondente, mas agenda uma chamada
     para o tratador associado (se existir). Se você quer realmente
     emitir o sinal, use "signal.raise_signal()".

_thread.exit()

   Levanta a exceção "SystemExit". Quando não for detectada, o thread
   sairá silenciosamente.

_thread.allocate_lock()

   Retorna um novo objeto de trava. Métodos de trava são descritos
   abaixo. A trava é desativada inicialmente.

_thread.get_ident()

   Retorna o 'identificador de thread' do thread atual. Este é um
   número inteiro diferente de zero. Seu valor não tem significado
   direto; pretende-se que seja um cookie mágico para ser usado, por
   exemplo, para indexar um dicionário de dados específicos do thread.
   identificadores de thread podem ser reciclados quando um thread sai
   e outro é criado.

_thread.get_native_id()

   Retorna a ID de thread integral nativa da thread atual atribuída
   pelo kernel. Este é um número inteiro não negativo. Seu valor pode
   ser usado para identificar exclusivamente essa thread específica em
   todo o sistema (até que a thread termine, após o que o valor poderá
   ser reciclado pelo sistema operacional).

   Disponibilidade

   Adicionado na versão 3.8.

   Alterado na versão 3.13: Adicionado suporte a GNU/kFreeBSD.

_thread.stack_size([size])

   Retorna o tamanho da pilha de threads usado ao criar novos threads.
   O argumento opcional *size* especifica o tamanho da pilha a ser
   usado para threads criados posteriormente e deve ser 0 (usar
   plataforma ou padrão configurado) ou um valor inteiro positivo de
   pelo menos 32.768 (32 KiB). Se *size* não for especificado, 0 será
   usado. Se a alteração do tamanho da pilha de threads não for
   suportada, uma "RuntimeError" será levantada. Se o tamanho da pilha
   especificado for inválido, uma "ValueError" será levantada e o
   tamanho da pilha não será modificado. Atualmente, 0 KiB é o valor
   mínimo de tamanho de pilha suportado para garantir espaço
   suficiente para o próprio interpretador. Observe que algumas
   plataformas podem ter restrições específicas sobre valores para o
   tamanho da pilha, como exigir um tamanho mínimo de pilha > 32 KiB
   ou exigir alocação em múltiplos do tamanho da página de memória do
   sistema -- a documentação da plataforma deve ser consultada para
   obter mais informações (4 páginas KiB são comuns; usar múltiplos de
   4096 para o tamanho da pilha é a abordagem sugerida na ausência de
   informações mais específicas).

   Disponibilidade

   Plataformas Unix com suporte a threads POSIX.

_thread.TIMEOUT_MAX

   O valor máximo permitido para o parâmetro *timeout* de
   "Lock.acquire". A especificação de um tempo limite maior que esse
   valor vai levantar um "OverflowError".

   Adicionado na versão 3.2.

Os objetos de trava têm os seguintes métodos:

lock.acquire(blocking=True, timeout=-1)

   Sem nenhum argumento opcional, esse método adquire a trava
   incondicionalmente, se necessário, aguardando até que seja liberada
   por outro encadeamento (apenas um encadeamento por vez pode
   adquirir uma trava --- esse é o motivo da sua existência).

   Se o argumento inteiro *blocking* estiver presente, a ação
   dependerá do seu valor: se for falso, a trava será adquirida apenas
   se puder ser adquirida imediatamente sem aguardar, enquanto se for
   verdadeiro, a trava será adquirida incondicionalmente, conforme
   acima.

   Se o argumento de ponto flutuante *timeout* estiver presente e
   positivo, ele especificará o tempo máximo de espera em segundos
   antes de retornar. Um argumento negativo *timeout* especifica uma
   espera ilimitada. Você não pode especificar um *timeout* se
   *blocking* for falso.

   O valor de retorno é "True" se a trava for adquirida com sucesso,
   se não "False".

   Alterado na versão 3.2: O parâmetro *timeout* é novo.

   Alterado na versão 3.2: As aquisições de trava agora podem ser
   interrompidas por sinais no POSIX.

lock.release()

   Libera a trava. A trava deve ter sido adquirido anteriormente, mas
   não necessariamente pela mesma thread.

lock.locked()

   Retorna o status da trava: "True" se tiver sido adquirida por
   alguma thread, "False" se não for o caso.

Além desses métodos, os objetos de trava também podem ser usados
através da instrução "with", por exemplo:

   import _thread

   a_lock = _thread.allocate_lock()

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

**Ressalvas:**

* Interrupts always go to the main thread (the "KeyboardInterrupt"
  exception will be received by that thread.)

* Chamar "sys.exit()" ou levantar a exceção "SystemExit" é o
  equivalente a chamar "_thread.exit()".

* It is platform-dependent whether the "acquire()" method on a lock
  can be interrupted (so that the "KeyboardInterrupt" exception will
  happen immediately, rather than only after the lock has been
  acquired or the operation has timed out). It can be interrupted on
  POSIX, but not on Windows.

* Quando a thread principal se encerra, é definido pelo sistema se as
  outras threads sobrevivem. Na maioria dos sistemas, elas são
  eliminadas sem executar cláusulas "try" ... "finally" ou executar
  destruidores de objetos.
