V2

[Yiling-J]

Theine V2 Migration Guide

Theine V2 is a major refactor and rewrite of V1, focused on thread safety and scalability. Below are the key changes:

Cache Class and Memoize Decorator

In V2, the Cache class and Memoize decorator now accept capacity as the first parameter. We have simplified the design by consolidating to a single policy: adaptive W-Tinylfu.

Old:

cache = Cache("tlfu", 10000)

@Memoize(Cache("tlfu", 10000), timedelta(seconds=100))
...

New:

cache = Cache(10000)

@Memoize(10000, timedelta(seconds=100))
...

Renaming timeout to ttl

The timeout parameter in the Cache class’s set method has been renamed to ttl (Time-to-Live). This is more commonly used in caching and is clearer in meaning. In V1, the term timeout was used for consistency with Django, but ttl is now the preferred naming convention in V2. The Django adapter settings still uses TIMEOUT for compatibility.

Old:

cache.set("key", {"foo": "bar"}, timeout=timedelta(seconds=100))

@Memoize(Cache("tlfu", 10000), timeout=timedelta(seconds=100))
...

New:

cache.set("key", {"foo": "bar"}, ttl=timedelta(seconds=100))

@Memoize(Cache("tlfu", 10000), ttl=timedelta(seconds=100))

Thread Safety by Default

In V2, both the Cache class and the Memoize decorator are thread-safe by default. However, if you're not using Theine in a multi-threaded environment, you can disable the locking mechanism. However for free-threaded Python build, nolock will always be False, even if set to True here. This is because Theine internally uses an extra thread for proactive expiry, so at least two threads are active, and thus nolock must remain False.

cache = Cache(10000, nolock=True)

@Memoize(10000, timedelta(seconds=100), nolock=True)
...

In V1, there was a lock parameter used to prevent cache stampede. In V2, this protection is enabled by default, so the lock parameter is no longer required. Setting nolock to True will disable the cache stampede protection, as cache stampede is not possible in a single-threaded environment.

Single Expiration Handling Thread for All Cache Instances

In V2, instead of each cache instance using a separate thread for proactive expiration (as in V1), a single thread will be used to handle expirations for all cache instances via asyncio. This improves efficiency and scalability.