Controlar tempo e memória de caches com lru_cache

Memoização guarda o resultado de uma chamada para associá-lo aos argumentos usados. Em uma chamada futura com os mesmos argumentos, o programa pode devolver o resultado já obtido em vez de executar novamente o corpo da função.

Isso só é correto quando deixar de executar o corpo não altera o comportamento que a função promete.

A mesma entrada pode seguir por dois caminhos: calcular na primeira vez e reutilizar o resultado nas repetições.

Uma função adequada não necessariamente merece cache. Se quase todas as chamadas usam argumentos novos, haverá pouca oportunidade de reutilizar resultados. Além disso, consultar e manter um cache também tem custos de tempo e memória.

A decisão completa exige observar o padrão real de chamadas. Nos próximos passos, você aplicará um cache limitado e verificará seus sinais de uso.

Importe lru_cache de functools e aplique @lru_cache(maxsize=...) imediatamente acima de uma função síncrona. Use um maxsize positivo e explícito: ele define quantas entradas o cache poderá manter, não o tamanho delas em bytes.

A cada chamada, o decorador monta uma chave a partir dos argumentos posicionais e nomeados. Se encontra essa chave, devolve o resultado guardado; se não encontra, executa a função e armazena o resultado para uma chamada futura equivalente.

A chamada repetida pode evitar a execução do corpo da função.

Crie um arquivo Python, cole o código completo abaixo e execute-o. O print dentro da função torna visível quando o corpo realmente foi executado.

Exemplo completo para execução local.

Todos os argumentos posicionais e nomeados usados em uma chamada devem ser hasháveis. Valores como int, str, bytes e tuplas formadas apenas por valores hasháveis são candidatos usuais. Uma list é mutável e não é hashável; por isso não pode compor a chave.

A exigência é dos argumentos, não do retorno: a função pode retornar uma lista. Ainda assim, escolha argumentos cuja igualdade e hash não mudem enquanto puderem ser usados como chave.

Acrescente estas linhas ao mesmo arquivo e execute novamente.

O método cache_info() retorna uma estrutura com quatro números importantes:

• hits: chamadas que reutilizaram uma entrada já armazenada.
• misses: chamadas cuja chave não estava no cache e, por isso, executaram a função antes de armazenar o resultado.
• maxsize: capacidade máxima configurada em quantidade de entradas.
• currsize: quantidade de entradas armazenadas agora.

Um miss não é uma exceção: é apenas uma ausência normal no cache. E maxsize limita entradas, não bytes; duas entradas podem reter quantidades de memória muito diferentes.

A sequência abaixo ilustra um cache com duas entradas.

Execute este exemplo localmente após as chamadas para inspecionar o estado.

Com maxsize=2, acompanhe dobrar(1), dobrar(2), dobrar(1), dobrar(3):

1. 1: miss; cache contém 1.
2. 2: miss; cache contém 1, 2. A menos recente é 1.
3. 1: hit; 1 passa a ser a mais recente. Agora a menos recente é 2.
4. 3: miss; seria necessária uma terceira entrada. O cache descarta 2 e mantém 1, 3.

Logo, após a sequência: hits=1, misses=3, currsize=2. LRU significa menos recentemente usada, não simplesmente “a primeira que entrou”.

Enquanto uma entrada permanece no lru_cache, o cache conserva referências aos argumentos que formam sua chave e ao resultado associado. Se esses objetos alcançam outros objetos, essa retenção também pode ser indireta.

Por isso, currsize informa quantas entradas estão ocupadas, não quantos bytes elas usam. Duas entradas podem conter resultados minúsculos; outras duas podem manter estruturas muito maiores. Também existe a sobrecarga das chaves e da própria estrutura do cache.

O cache mantém os objetos alcançáveis pelas referências presentes na chave e no resultado.

Quando lru_cache decora um método de instância, uma chamada como catalogo.resumo("python") usa self — isto é, a instância catalogo — como parte da chave, além dos demais argumentos.

O método decorado fica na classe e seu cache é compartilhado entre instâncias. Assim, uma entrada pode manter a instância viva por meio da referência a self. Como self participa da chave, ele precisa ser hashável. Uma classe comum costuma herdar hash por identidade; porém, uma classe que define igualdade e não define um hash compatível pode se tornar não hashável.

A chave de cada chamada identifica tanto a instância quanto os outros argumentos.

Execute este script localmente. Ele cria resultados imutáveis de tamanhos controlados e não guarda os retornos em uma lista ou variável externa. A medição usa somente tracemalloc; uma comparação de tempo deve ser um experimento separado, sem essa instrumentação.

Salve como memoria_cache.py e execute com Python 3.

lru_cache não tem expiração por tempo e não observa automaticamente arquivos, configurações, bancos de dados, serviços externos nem atributos alteráveis de uma instância. Um acerto apenas informa que a chave já está armazenada; ele não confirma que a fonte ainda contém o mesmo dado.

Por isso, usar muito uma entrada pode mantê-la recente no cache, mas não a torna atual. Quando uma mudança relevante ocorre na fonte, sua aplicação precisa executar uma política explícita de invalidação antes das próximas consultas que exigem dados novos.

A mesma chamada continua encontrando a entrada já armazenada, mesmo depois de a fonte externa mudar.

O dicionário representa uma fonte externa ao argumento de preco_com_desconto. A chave do cache é apenas produto; portanto, mudar a taxa não cria uma nova chave.

preco_com_desconto.cache_clear() remove todas as entradas daquele cache e reinicia hits e misses. Assim, a próxima chamada não encontra a chave e executa o corpo da função novamente.

A limpeza remove as referências que o cache mantinha para seus argumentos e resultados. Isso não destrói objetos que ainda tenham outras referências no programa; apenas deixa de ser o cache quem os mantém vivos.

Em uma chamada com a mesma chave, lru_cache devolve o objeto que foi armazenado no primeiro cálculo. Se esse objeto for mutável, como uma lista ou dicionário, consumidores diferentes passam a compartilhar o mesmo estado.

O segundo retorno aponta para a mesma lista já guardada pelo cache.

Execute este script. A segunda chamada é um hit para a mesma chave.

Se os consumidores não precisam modificar o retorno, prefira armazenar e devolver uma estrutura efetivamente imutável, como uma tupla. Se cada consumidor precisa de uma estrutura mutável própria, mantenha o cache em uma função interna e faça a cópia em uma camada externa, depois do hit.

Aqui o cache guarda uma tupla imutável. A função pública cria uma lista nova em cada chamada.

Um acerto evita o cálculo, mas uma chamada com cache ainda consulta a chave, calcula hashes, mantém a estrutura LRU e pode exigir cópias em uma camada externa quando o contrato pede objetos independentes.

Compare a mesma sequência de argumentos em três cenários: sem cache, cache vazio e cache aquecido. O ganho depende de quanto custa o cálculo evitado, da repetição das chaves e da capacidade disponível.

Copie o script inteiro para um arquivo, por exemplo comparar_cache.py, e execute com python comparar_cache.py. A função decorada não é recursiva; por isso, calcular.__wrapped__ fornece uma linha de base sem cache para o mesmo corpo da função.

No padrão concentrado, há somente 8 chaves para maxsize=16. No cache vazio, as primeiras ocorrências tendem a ser misses e as demais podem ser hits; no aquecido, o lote tende a começar com hits.

Na alta cardinalidade, há 400 chaves distintas. Preparar todas não faz todas caberem: o LRU mantém no máximo 16 entradas. Ao percorrer novamente a sequência em ordem, as entradas antigas podem ser descartadas antes de serem reutilizadas. Assim, o cache pode acrescentar custo sem evitar cálculo suficiente.

Quando várias threads usam uma função decorada com lru_cache, a estrutura interna do cache permanece coerente: acessos e atualizações não devem corromper suas entradas nem seus contadores.

Mas essa garantia não transforma um miss em trabalho exclusivo. O cache reutiliza resultados que já foram concluídos e armazenados; ele não reserva automaticamente uma chave ausente para uma única thread calcular.

A janela importante ocorre entre a consulta que encontra a chave ausente e o armazenamento do resultado.

Use lru_cache para reutilizar resultados concluídos de cálculos seguros de repetir. Trate a coordenação de trabalho em andamento como outro problema, especialmente quando duplicar a execução é caro ou altera o mundo externo.

Considere buscar_produto(codigo), que consulta um catálogo em memória. Para a mesma versão do catálogo e o mesmo código, a função deve devolver dados equivalentes e não tem efeito colateral. A carga real concentra consultas em 24 códigos populares, mas pode receber milhares de códigos diferentes ao longo do dia.

Medições locais com a mesma carga mostram:

• Sem cache: 84 ms por lote.
• lru_cache(maxsize=32) aquecido: 19 ms; 91% de acertos; currsize=32.
• lru_cache(maxsize=None) aquecido: 18 ms; 92% de acertos; currsize=18.400 após um período maior.

Cada entrada retém os argumentos e o resultado. O orçamento do processo permite um cache pequeno, mas não crescimento contínuo.

Compare o pequeno ganho adicional sem limite com o crescimento de entradas retidas.

Uma recomendação completa responde a estas perguntas:

1. Correção: o resultado depende apenas de argumentos e de uma fonte considerada estável entre invalidações?
2. Tempo: os tempos e a taxa de acertos foram medidos com o padrão relevante de chamadas, comparando cache vazio, aquecido e linha de base?
3. Memória: currsize e o tamanho potencial de argumentos/resultados cabem no orçamento? Lembre-se: currsize não mede bytes.
4. Ciclo de vida: qual evento chama cache_clear() e quem é responsável por isso?

Se o retorno for mutável e cada consumidor precisar de independência, a camada externa ao cache deve devolver uma cópia adequada — ou o contrato deve retornar uma estrutura imutável.