_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: Agora este é um sinônimo da exceção embutida
RuntimeError
.
- _thread.LockType¶
Este é o tipo de objetos de trava.
- _thread.start_new_thread(function, args[, kwargs])¶
Começa uma nova thread e retorna seu identificador. A thread 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 nomeados.
Quando a função retorna, a thread termina 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) é exibido e, em seguida, a thread termina (mas outras threads continuam a ser executadas).Quando a função gera uma exceção
SystemExit
, ela é ignorada.Levanta um evento de auditoria
_thread.start_new_thread
com os argumentosfunction
,args
,kwargs
.Alterado na versão 3.8:
sys.unraisablehook()
agora é usada para tratar exceções não tratadas.
- _thread.interrupt_main(signum=signal.SIGINT, /)¶
Simula 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 pelo Python (o sinal foi definido como
signal.SIG_DFL
ousignal.SIG_IGN
), esta funçã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, a thread terminará 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’ da 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 uma thread termina e outra é criada.
- _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).
Availability: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD, GNU/kFreeBSD.
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 novas threads. O argumento opcional size especifica o tamanho da pilha a ser usado para threads criadas 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 permitida, uma
RuntimeError
será levantada. Se o tamanho da pilha especificado for inválido, umValueError
será levantado 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).Availability: Windows, pthreads.
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 umOverflowError
.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 outra thread (apenas uma thread 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ãoFalse
.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
uma_trava = _thread.allocate_lock()
with uma_trava:
print("uma_trava está travada enquanto isto executa")
Ressalvas:
Interrupções sempre vão para a thread principal (a exceção
KeyboardInterrupt
será recebida por essa thread).Chamar
sys.exit()
ou levantar a exceçãoSystemExit
é o equivalente a chamar_thread.exit()
.O método
acquire()
de uma trava ser interrompido depende da plataforma (de modo que a exceçãoKeyboardInterrupt
acontecerá imediatamente, em vez de quando a trava for travada, ou quando a operação ultrapassar o tempo limite). O método pode ser interrompido em POSIX, mas não em Windows.Quando a thread principal se encerra, o fato de outras threads sobreviverem depende do sistema. Na maioria dos sistemas, elas são eliminadas sem executar cláusulas
try
…finally
ou destruidores de objetos.