Caching

coredis.patterns.cache

Built in caches

class LRUCache(max_keys: int = 2**12, confidence: float = 100, dynamic_confidence: bool = False)

Implementation of an LRU cache that can be used with Redis or coredis.RedisCluster

Parameters:

• max_keys – maximum keys to cache. A negative value represents and unbounded cache.

• confidence – 0 - 100. Lower values will result in the client discarding and / or validating the cached responses

• dynamic_confidence – Whether to adjust the confidence based on sampled validations. Tainted values drop the confidence by 0.1% and confirmations of correct cached values will increase the confidence by 0.01% upto 100.

put(command: bytes, key: RedisValueT, *args: RedisValueT, value: ResponseType) → None

Cache the response for command/key/args combination

get(command: bytes, key: RedisValueT, *args: RedisValueT) → ResponseType

Fetch the cached response for command/key/args combination

invalidate(*keys: RedisValueT) → None

Invalidate any cached entries for the provided keys

reset() → None

Reset the cache

property stats: CacheStats

Returns the current stats for the cache

property confidence: float

Confidence in cached values between 0 - 100. Lower values will result in the client discarding and / or validating the cached responses

feedback(command: bytes, key: RedisValueT, *args: RedisValueT, match: bool) → None

Provide feedback about a key as having either a match or drift from the actual server side value

property healthy: bool

The LRU Cache is always “healthy”

Implementing a custom cache

All caches accepted by Redis or RedisCluster must implement AbstractCache

class AbstractCache

Abstract class representing a local cache that can be used by Redis or coredis.RedisCluster

abstractmethod get(command: bytes, key: RedisValueT, *args: RedisValueT) → ResponseType

Fetch the cached response for command/key/args combination

abstractmethod put(command: bytes, key: RedisValueT, *args: RedisValueT, value: ResponseType) → None

Cache the response for command/key/args combination

abstractmethod invalidate(*keys: RedisValueT) → None

Invalidate any cached entries for the provided keys

abstractmethod reset() → None

Reset the cache

abstract property stats: CacheStats

Returns the current stats for the cache

abstract property confidence: float

Confidence in cached values between 0 - 100. Lower values will result in the client discarding and / or validating the cached responses

abstractmethod feedback(command: bytes, key: RedisValueT, *args: RedisValueT, match: bool) → None

Provide feedback about a key as having either a match or drift from the actual server side value

abstract property healthy: bool

Whether the cache is healthy and should be taken seriuosly

class CacheStats(hits: Counter[bytes] = <factory>, misses: Counter[bytes] = <factory>, invalidations: Counter[bytes] = <factory>, dirty: Counter[bytes] = <factory>)

Summary of statics to be used by instances of AbstractCache The individual counters exposed are not guaranteed to retain fine grained per key metrics but the totals (returned by coredis.patterns.cache.CacheStats.summary) will be maintained aggregated.

hits: Counter[bytes]

summary of hits by key (for all commands)

misses: Counter[bytes]

summary of misses by key (for all commands)

invalidations: Counter[bytes]

number of invalidations including server side and local invalidations

dirty: Counter[bytes]

counter of keys which returned dirty results based on confidence testing

property summary: dict[str, int]

Aggregated totals of hits, misses, dirty_hits and invalidations

Internal cache wrappers

class NodeTrackingCache(connection_pool: BaseConnectionPool[ConnectionT], cache: AbstractCache | None = None, max_idle_seconds: float = 15)

Wraps an AbstractCache instance to use server assisted client caching to ensure local cache entries are invalidated if any operations are performed on the keys by another client.

Parameters:

• connection_pool – Connection pool used to acquire a connection for the tracking connection

• cache – AbstractCache instance to wrap

• max_idle_seconds – Maximum duration (in seconds) to tolerate no updates from the server before performing a keepalive check with a PING. If no updates or successful ping occur within this period, the cache is considered unhealthy (as reflected by the healthy property).

property healthy: bool

Whether the cache is healthy and should be taken seriuosly

async run(task_status: TaskStatus[None] = TASK_STATUS_IGNORED) → None

Run a single connection that listens for invalidation messages, with reconnection logic.

property confidence: float

Confidence in cached values between 0 - 100. Lower values will result in the client discarding and / or validating the cached responses

feedback(command: bytes, key: RedisValueT, *args: RedisValueT, match: bool) → None

Provide feedback about a key as having either a match or drift from the actual server side value

get(command: bytes, key: RedisValueT, *args: RedisValueT) → ResponseType

Fetch the cached response for command/key/args combination

invalidate(*keys: RedisValueT) → None

Invalidate any cached entries for the provided keys

put(command: bytes, key: RedisValueT, *args: RedisValueT, value: ResponseType) → None

Cache the response for command/key/args combination

reset() → None

Reset the cache

property stats: CacheStats

Returns the current stats for the cache

class ClusterTrackingCache(connection_pool: BaseConnectionPool[ClusterConnection], cache: AbstractCache | None = None, max_idle_seconds: float = 15)

An LRU cache for redis cluster that uses server assisted client caching to ensure local cache entries are invalidated if any operations are performed on the keys by another client.

The cache maintains an additional connection per node (including replicas) in the cluster to listen to invalidation events

property confidence: float

Confidence in cached values between 0 - 100. Lower values will result in the client discarding and / or validating the cached responses

feedback(command: bytes, key: RedisValueT, *args: RedisValueT, match: bool) → None

Provide feedback about a key as having either a match or drift from the actual server side value

get(command: bytes, key: RedisValueT, *args: RedisValueT) → ResponseType

Fetch the cached response for command/key/args combination

property healthy: bool

Whether the cache is healthy and should be taken seriuosly

invalidate(*keys: RedisValueT) → None

Invalidate any cached entries for the provided keys

put(command: bytes, key: RedisValueT, *args: RedisValueT, value: ResponseType) → None

Cache the response for command/key/args combination

reset() → None

Reset the cache

property stats: CacheStats

Returns the current stats for the cache