Theine

受 Caffeine 启发的高性能内存缓存。

高性能 Rust 核心
使用 W-TinyLFU 或 Clock-Pro 淘汰策略实现高命中率
使用层级时间轮自动移除过期数据

在内存缓存中必须考虑 TTL，因为它限制了有效（未过期）的工作集大小。高效地从缓存中移除过期对象的优先级应高于缓存淘汰。 - Twitter 数百个内存缓存集群的大规模分析
简单的 API
Django 缓存后端

要求

Python 3.7+

安装

pip install theine

缓存淘汰策略

Theine 提供 3 种内置的缓存淘汰策略：

LRU

首先丢弃最近最少使用的项目。

W-TinyLFU

一种近似 LFU 策略，用于提高面对倾斜访问分布的缓存效率。

Theine 使用 W-TinyLFU 的自适应版本，以在不同类型的工作负载下获得更好的命中率。

参考：

https://arxiv.org/pdf/1512.00727.pdf

Clock-PRO

一种改进的 CLOCK 替换策略（CLOCK：LRU 的近似），基于 PyClockPro。

参考：

https://static.usenix.org/event/usenix05/tech/general/full_papers/jiang/jiang_html/html.html

API

键应该是可哈希对象，值可以是任何 Python 对象。如果键类型不是 str/int，Theine 将自动生成一个唯一的键字符串，这个唯一字符串会在内存中占用额外空间并增加 get/set/remove 的开销。

每个 Cache 实例会启动一个线程主动驱逐过期条目，缓存实例初始化的开销相对较高。因此不要在函数中动态创建实例。Django 适配器会自动创建一个全局缓存实例，使用 Memoize 装饰器时，请确保你的缓存实例是全局创建的，而不是在每次运行时创建一个新实例。

请注意 Cache 类不是线程安全的。

from theine import Cache
from datetime import timedelta

# tlfu 是淘汰策略，Theine 提供 3 种策略 lru/tlfu/clockpro
cache = Cache("tlfu", 10000)
# 没有默认值时，未命中返回 None
v = cache.get("key")

# 有默认值时，未命中返回默认值
sentinel = object()
v = cache.get("key", sentinel)

# 设置带 ttl 的缓存
cache.set("key", {"foo": "bar"}, timedelta(seconds=100))

# 从缓存中删除
cache.delete("key")

# 关闭缓存，停止时间轮线程
cache.close()

# 清空缓存
cache.clear()

# 获取当前缓存统计，如需更新的统计请再次调用 stats()
stats = cache.stats()
print(stats.request_count, stats.hit_count, stats.hit_rate)

# 获取缓存最大大小
cache.max_size

# 获取缓存当前大小
len(cache)

装饰器

Theine 支持可哈希键，所以使用装饰器时，需要一个将输入签名转换为可哈希的函数。推荐的方式是显式指定函数，这是方法 1，Theine 也支持自动生成键，这是方法 2。与 Theine API 相同，如果键函数返回类型不是 str/int，Theine 将自动生成一个唯一的键字符串，这个唯一字符串会在内存中占用额外空间并增加 get/set/remove 的开销。

- 显式键函数

from theine import Cache, Memoize
from datetime import timedelta

@Memoize(Cache("tlfu", 10000), timedelta(seconds=100))
def foo(a:int) -> int:
    return a

@foo.key
def _(a:int) -> str:
    return f"a:{a}"

foo(1)

# asyncio
@Memoize(Cache("tlfu", 10000), timedelta(seconds=100))
async def foo_a(a:int) -> int:
    return a

@foo_a.key
def _(a:int) -> str:
    return f"a:{a}"

await foo_a(1)

优点

同时支持同步和异步。
显式控制键的生成方式。大多数远程缓存（redis, memcached...）只允许字符串键，在键函数中返回字符串使得将来使用远程缓存更容易。
雷鸣群保护（多线程：在 Memoize 中设置 lock=True，asyncio：始终启用）。
类型检查。Mypy 可以检查键函数以确保它具有与原始函数相同的输入签名并返回可哈希对象。

缺点

你必须使用两个函数。
性能。Theine API：约 8ms/10k 请求 ->> 装饰器：约 12ms/10k 请求。

- 自动键函数

from theine import Cache, Memoize
from datetime import timedelta

@Memoize(Cache("tlfu", 10000), timedelta(seconds=100), typed=True)
def foo(a:int) -> int:
    return a

foo(1)

# asyncio
@Memoize(Cache("tlfu", 10000), timedelta(seconds=100), typed=True)
async def foo_a(a:int) -> int:
    return a

await foo_a(1)

优点

与显式键版本相同。
无需额外的键函数。

缺点

性能较差:约18毫秒/1万次请求。
意外的内存使用。自动键函数使用与Python的lru_cache相同的方法。请查看这个问题或这个问题。

Django缓存后端

CACHES = {
    "default": {
        "BACKEND": "theine.adapters.django.Cache",
        "TIMEOUT": 300,
        "OPTIONS": {"MAX_ENTRIES": 10000, "POLICY": "tlfu"},
    },
}

元数据内存开销

假设您的键长为24字节，那么Rust中每个元键条目占92字节。对于100万个键，总内存开销为92兆字节。Clock-Pro将使用2倍的元空间，即184兆字节。

基准测试

Python版本: 3.11

操作系统: Ubuntu 22.04.2 LTS

持续基准测试

https://github.com/Yiling-J/cacheme-benchmark

1万次请求

Cachetools: https://github.com/tkem/cachetools

Cacheout: https://github.com/dgilland/cacheout

源代码: https://github.com/Yiling-J/theine/blob/main/benchmarks/benchmark_test.py

写入和混合Zipf使用1千的最大缓存大小，所以这里您可以看到传统LFU驱逐策略的高成本。

	读取	写入	混合Zipf
Theine(Clock-Pro) API	3.07 毫秒	9.86 毫秒
Theine(W-TinyLFU) API	3.42 毫秒	10.14 毫秒
Theine(W-TinyLFU) 自动键装饰器	7.17 毫秒	18.41 毫秒	13.18 毫秒
Theine(W-TinyLFU) 自定义键装饰器	6.45 毫秒	17.67 毫秒	11.50 毫秒
Cachetools LFU 装饰器	15.70 毫秒	627.10 毫秒	191.04 毫秒
Cacheout LFU 装饰器	50.05 毫秒	704.70 毫秒	250.95 毫秒
Theine(LRU) 自定义键装饰器	5.70 毫秒	16.04 毫秒	10.91 毫秒
Cachetools LRU 装饰器	14.05 毫秒	61.06 毫秒	36.89 毫秒
Cacheout LRU 装饰器	47.90 毫秒	94.94 毫秒	68.25 毫秒