# Suporte do Python para threads livres

A partir da versão 3.13, o CPython tem suporte para uma compilação do Python chamada threads livres (em inglês, free threading), onde a trava global do interpretador (GIL) está desabilitada. A execução com threads livres permite a utilização total do poder de processamento disponível, executando threads em paralelo nos núcleos de CPU disponíveis. Embora nem todos os softwares se beneficiem disso automaticamente, os programas projetados com uso de threads em mente serão executados mais rapidamente em hardware com vários núcleos.

O modo com threads livres está funcionando e continua sendo aprimorado, mas há alguma sobrecarga adicional em cargas de trabalho de thread única em comparação com a construção regular. Além disso, pacotes de terceiros, em particular aqueles com um módulo de extensão, podem não estar prontos para uso em uma construção com threads livres e reativarão a GIL.

Este documento descreve as implicações de threads livres para o código Python. Veja Suporte a extensões da API C para threads livres para informações sobre como escrever extensões C que oferecem suporte à construção com threads livres.

Ver também

PEP 703 – Tornando a trava global do interpretador opcional no CPython para uma descrição geral do Python com threads livres.

## Instalação

A partir do Python 3.13, os instaladores oficiais do macOS e do Windows oferecem suporte opcional à instalação de binários Python com threads livres. Os instaladores estão disponíveis em https://www.python.org/downloads/.

Para obter informações sobre outras plataformas, consulte Instalando um Python com threads livres, um guia de instalação mantido pela comunidade para instalar o Python com threads livres.

Ao construir o CPython a partir do código-fonte, a opção de configuração `--disable-gil` deve ser usada para construir um interpretador Python com threads livres.

## Identificando um Python com threads livres

Para verificar se o interpretador atual oferece suporte a threads livres, `python -VV` e `sys.version` contêm “free-threading build”. A nova função `sys._is_gil_enabled()` pode ser usada para verificar se a GIL está realmente desabilitada no processo em execução.

A variável de configuração `sysconfig.get_config_var("Py_GIL_DISABLED")` pode ser usada para determinar se a compilação tem suporte a threads livres. Se a variável for definida como `1`, a compilação tem suporte a threads livres. Este é o mecanismo recomendado para decisões relacionadas à configuração da construção.

## A trava global do interpretador no Python com threads livres

Construções com threads livres do CPython oferecem suporte a opcionalmente executar com a GIL habilitada em tempo de execução usando a variável de ambiente `PYTHON_GIL` ou a opção de linha de comando `-X gil`.

A GIL também pode ser habilitada automaticamente ao importar um módulo de extensão da API C que não esteja explicitamente marcado como oferecendo suporte a threads livres. Um aviso será impresso neste caso.

Além da documentação de pacotes individuais, os seguintes sites rastreiam o status do suporte de pacotes populares para threads livres:

- https://py-free-threading.github.io/tracking/

- https://hugovk.github.io/free-threaded-wheels/

## Segurança nas threads

A construção com threads livres do CPython visa fornecer comportamento de segurança às threads semelhante no nível do Python à construção padrão com GIL habilitada. Tipos embutidos como `dict`, `list` e `set` usam travas internas para proteger contra modificações simultâneas de maneiras que se comportam de forma semelhante à GIL. No entanto, o Python não garantiu historicamente um comportamento específico para modificações simultâneas a esses tipos embutidos, portanto, isso deve ser tratado como uma descrição da implementação atual, não uma garantia de comportamento atual ou futuro.

Nota

É recomendável usar `threading.Lock` ou outras primitivas de sincronização em vez de depender de travas internas de tipos embutidos, quando possível.

## Limitações conhecidas

Esta seção descreve as limitações conhecidas da construção do Python com threads livres.

### Imortalização

A construção com threads livres da versão 3.13 torna alguns objetos imortais. Objetos imortais não são desalocados e têm contagens de referência que nunca são modificadas. Isso é feito para evitar contenção de contagem de referências que impediria o dimensionamento multithread eficiente.

Um objeto será tornado imortal quando um novo thread for iniciado pela primeira vez após o thread principal estar em execução. Os seguintes objetos são imortalizados:

- objetos função declarados no nível de módulo

- descritores de métodos

- objetos código

- objetos módulo e seus dicionários

- classes (objetos de tipo)

Como objetos imortais nunca são desalocados, aplicações que criam muitos objetos desses tipos podem ver aumento no uso de memória. Espera-se que isso seja resolvido na versão 3.14.

Além disso, literais numéricos e de string no código, bem como strings retornadas por `sys.intern()` também são imortalizados. Espera-se que esse comportamento permaneça na construção com threads livres do 3.14.

### Objetos quadro

Não é seguro acessar objetos quadro de outros threads e fazer isso pode fazer com que seu programa trave. Isso significa que `sys._current_frames()` geralmente não é seguro para uso em uma construção com threads livres. Funções como `inspect.currentframe()` e `sys._getframe()` são geralmente seguras, desde que o objeto quadro resultante não seja passado para outro thread.

### Iteradores

Compartilhar o mesmo objeto iterador entre vários threads geralmente não é seguro e os threads podem ver elementos duplicados ou ausentes ao iterar ou travar o interpretador.

### Desempenho com thread única

A construção com threads livres tem sobrecarga adicional ao executar código Python em comparação com a construção padrão com GIL habilitada. Na versão 3.13, essa sobrecarga é de cerca de 40% no conjunto de ferramentas pyperformance. Programas que passam a maior parte do tempo em extensões C ou E/S verão menos impacto. O maior impacto é porque o interpretador adaptativo especializado (PEP 659) está desabilitado na construção com threads livres. Esperamos reabilitá-lo de forma segura para threads na versão 3.14. Espera-se que essa sobrecarga seja reduzida na próxima versão do Python. Estamos buscando uma sobrecarga de 10% ou menos no conjunto de ferramentas pyperformance em comparação com a construção padrão com GIL habilitada.

## Mudanças comportamentais

Esta seção descreve as mudanças comportamentais do CPython com a construção com threads livres.

### Variáveis de contexto

Na construção com threads livres, o sinalizador `thread_inherit_context` é definido como true por padrão, o que faz com que threads criadas com `threading.Thread` iniciem com uma cópia de `Context()` do chamador de `start()`. Na construção padrão com GIL habilitada, o sinalizador é definido como false por padrão, então as threads iniciam com um `Context()` vazio.

### Filtros de aviso

Na construção com threads livres, o sinalizador `context_aware_warnings` é definido como verdadeiro por padrão. Na construção com GIL habilitada, o sinalizador é definido como falso por padrão. Se o sinalizador for verdadeiro, o gerenciador de contexto `warnings.catch_warnings` usa uma variável de contexto para filtros de aviso. Se o sinalizador for falso, `catch_warnings` modifica a lista de filtros globais, o que não é seguro para thread. Consulte o módulo `warnings` para obter mais detalhes.