:mod:--- API de segmentação de baixo nível
******************************************

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

Este módulo fornece primitivos de baixo nível para trabalhar com
vários tópicos (também chamados: dfn: *light-weight processes* ou:
dfn:` tasks`) --- vários tópicos de controle compartilhando seu espaço
de dados global. Para sincronização, bloqueios simples (também
chamados de: dfn: *mutexes* ou: dfn:` binary semaphores`) são
fornecidos. O módulo: mod: *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 built-in: exc:
   *RuntimeError*.

_thread.LockType

   Este é o tipo de objetos de bloqueio.

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

   Inicie um novo encadeamento e retorne seu identificador. O
   encadeamento executa a função * function * com a lista de
   argumentos * args * (que deve ser uma tupla). O argumento opcional
   * kwargs * especifica um dicionário de argumentos de palavras-
   chave. Quando a função retorna, o segmento sai silenciosamente.
   Quando a função termina com uma exceção não tratada, um
   rastreamento de pilha é impresso e, em seguida, o segmento sai (mas
   outros segmentos continuam a ser executados).

_thread.interrupt_main()

   Simula o efeito de "signal.SIGINT" signal chegando na thread
   principal. Uma thread pode usar essa função para interromper a
   thread principal.

   Se "signal.SIGINT" não for manipulado pelo Python (foi definido
   como "signal.SIG_DFL" ou "signal.SIG_IGN"), essa função não faz
   nada.

_thread.exit()

   Gera a exceção:exc:*SystemExit*.  Quando não for detectada, o
   thread sairá silenciosamente.

_thread.allocate_lock()

   Retorna um novo objeto de bloqueio. Métodos de bloqueio são
   descritos abaixo. O bloqueio é desativado 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.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, um :exc: *RuntimeError* será gerado. Se o tamanho da
   pilha especificado for inválido, um :exc: *ValueError* será
   aumentado 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 intérprete. 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).

   Availability: Windows, systems with POSIX threads.

_thread.TIMEOUT_MAX

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

   Novo na versão 3.2.

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

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

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

   Se o argumento inteiro *waitflag* estiver presente, a ação
   dependerá do seu valor: se for zero, o bloqueio será adquirido
   apenas se puder ser adquirido imediatamente sem aguardar, enquanto
   se for diferente de zero, o bloqueio será adquirido
   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
   *waitflag* for zero.

   O valor de retorno é "True" se o bloqueio for adquirido 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 bloqueio agora podem ser
   interrompidas por sinais no POSIX.

lock.release()

   Libera o bloqueio. O bloqueio deve ter sido adquirido
   anteriormente, mas não necessariamente pela mesma thread.

lock.locked()

   Retorna o status do bloqueio: "True" se tiver sido adquirido por
   alguma thread, "False" se não for o caso.

Além desses métodos, os objetos de bloqueio 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:**

* Threads interagem estranhamente com interrupções: a exceção
  "KeyboardInterrupt" será recebida por uma thread arbitrário. (Quando
  o módulo "signal" está disponível, as interrupções sempre vão para a
  thread principal.)

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

* Não é possível interromper o método "acquire()" em um bloqueio --- a
  exceção "KeyboardInterrupt" ocorrerá após o bloqueio ter sido
  adquirido.

* 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.

* Quando a thread principal é encerrada, ela não realiza nenhuma
  limpeza usual (exceto que as cláusulas "try" ... "finally" são
  honradas) e os arquivos de E/S padrão não são liberados.
