pub struct HybridCacheStore<D, C = SystemClock>where
D: CacheStore + 'static,
C: Clock,{ /* private fields */ }hybrid only.Expand description
An in-memory layer in front of a distributed store, with invalidations carried by a
RedisBackplane.
One store holds values of every type: get::<User> and set(&key, user, None) name the type
per call.
Reads try the local layer, then the distributed one, and copy a distributed hit into the local layer with its original creation time and TTL. Writes and removals evict the local copy, update the distributed store, evict it again, and publish an invalidation so other nodes evict theirs. Reading a local copy as another Rust type goes to the distributed store instead, so two types that fit the same JSON can both read it.
The store applies other nodes’ invalidations on a backplane worker it starts on its first call
inside a tokio runtime, or in connect, and stops when its last clone drops. Until that worker
has subscribed, and while the subscription is lost, the store reads through to the distributed
store.
Implementations§
Source§impl<D> HybridCacheStore<D>where
D: CacheStore + 'static,
impl<D> HybridCacheStore<D>where
D: CacheStore + 'static,
Sourcepub fn new(
distributed_store: D,
backplane: RedisBackplane,
settings: &HybridCacheSettings,
) -> Result<HybridCacheStore<D>, HybridCacheError>
pub fn new( distributed_store: D, backplane: RedisBackplane, settings: &HybridCacheSettings, ) -> Result<HybridCacheStore<D>, HybridCacheError>
Builds the store over distributed_store, with its invalidations on backplane, and the
local layer on each node from settings.local, named as the distributed store is.
settings also gives the store’s TTL, refresh and lock settings and the backplane
worker’s; settings.distributed is for connect, which builds the Redis
store, so set those on the store you pass here. Fails when a setting is out of range, or
when distributed_store has TTL, refresh or lock settings of its own, which hybrid calls
wouldn’t read.
On a Redis Cluster, the store takes a cluster connection and the backplane the cluster client, on RESP3 for its sharded pub/sub:
use sisa_caching_hybrid::{HybridCacheSettings, HybridCacheStore, RedisBackplane};
use sisa_caching_redis::{
RedisCacheStore,
redis::{ProtocolVersion, cluster::ClusterClientBuilder},
};
let client = ClusterClientBuilder::new(vec!["redis://10.0.0.1:6379"])
.use_protocol(ProtocolVersion::RESP3)
.build()?;
let cache = HybridCacheStore::new(
RedisCacheStore::new("app", client.get_async_connection().await?)?,
RedisBackplane::cluster(client).await?,
&HybridCacheSettings::default(),
)?;Behind Sentinel, RedisBackplane::sentinel shows the setup. On one server,
connect builds every part from a URL.
Source§impl<D, C> HybridCacheStore<D, C>where
D: CacheStore + 'static,
C: Clock,
impl<D, C> HybridCacheStore<D, C>where
D: CacheStore + 'static,
C: Clock,
Sourcepub fn start_worker(&self)
pub fn start_worker(&self)
Starts the backplane worker now instead of on the store’s first call, as connect does,
so local reads come on, and the sisa.caching.backplane.connected gauge reports, before
the first call. It does nothing outside a tokio runtime or once the worker has started.
Sourcepub fn node_id(&self) -> &NodeId
pub fn node_id(&self) -> &NodeId
This store’s id, shared by its clones. It goes out with every invalidation, so the store skips its own.
Sourcepub fn local_reads_enabled(&self) -> bool
pub fn local_reads_enabled(&self) -> bool
Whether reads use the local layer: only while the backplane worker is subscribed.
Sourcepub async fn shutdown(&self)
pub async fn shutdown(&self)
Tells the other nodes that this one is stopping, so they forget it instead of clearing
their local layers once its heartbeats have stopped for heartbeat_timeout_ms. Call it
once, as the application shuts down, after its last write.
It waits up to two seconds for the writes still running, even those whose caller gave up,
to publish their invalidations. Then it publishes one stopping message that counts every
write, so a node that missed one clears, and stops the backplane worker for good, for every
clone, so reads go to the distributed store from then on. The stop runs in a task of its
own, so a caller that gives up on it doesn’t cut it short, and every call, at the same time
or later, returns once it is done. A write after it still works, but the other nodes clear
once more when they don’t hear from this node again. A node that stops without calling it
costs every other node one clear.
Source§impl HybridCacheStore<RedisCacheStore>
impl HybridCacheStore<RedisCacheStore>
Sourcepub async fn connect(
name: &str,
info: impl IntoConnectionInfo,
settings: &HybridCacheSettings,
) -> Result<HybridCacheStore<RedisCacheStore>, HybridCacheError>
pub async fn connect( name: &str, info: impl IntoConnectionInfo, settings: &HybridCacheSettings, ) -> Result<HybridCacheStore<RedisCacheStore>, HybridCacheError>
Connects every part to one Redis server, such as redis://127.0.0.1:6379 (rediss://
with the tls-rustls or tls-native-tls feature): the local layer, the Redis store and
the backplane, each with its part of settings, and starts the backplane worker with
settings.worker. info is a URL or a redis::ConnectionInfo. Its connections use
connection_config: while Redis is down a call fails at once. For other timeouts, a client
built by hand, a cluster or Sentinel, build the parts and use new.
Trait Implementations§
Source§impl<D, C> CacheStore for HybridCacheStore<D, C>where
D: CacheStore + 'static,
C: Clock,
impl<D, C> CacheStore for HybridCacheStore<D, C>where
D: CacheStore + 'static,
C: Clock,
Source§type Error = HybridCacheError
type Error = HybridCacheError
CacheError converts into it.Source§fn cache_settings(&self) -> &CacheSettings
fn cache_settings(&self) -> &CacheSettings
Source§async fn get_entry<CV>(
&self,
key: &str,
) -> Result<Option<CacheEntry<CV>>, HybridCacheError>where
CV: CacheValue,
async fn get_entry<CV>(
&self,
key: &str,
) -> Result<Option<CacheEntry<CV>>, HybridCacheError>where
CV: CacheValue,
key as a CV, or None when it is missing or expired. The memory store
fails with CacheError::TypeMismatch when it holds another Rust type there. The Redis
store decodes its JSON into CV, so another type whose fields fit reads it too, and JSON
that doesn’t fit is an error. The entry is as it was when looked up: it can expire while
a slow Clone of its value, or its decoding, runs.Source§async fn set_entry<CV>(
&self,
key: &str,
entry: CacheEntry<CV>,
) -> Result<(), HybridCacheError>where
CV: CacheValue,
async fn set_entry<CV>(
&self,
key: &str,
entry: CacheEntry<CV>,
) -> Result<(), HybridCacheError>where
CV: CacheValue,
entry as it is: its creation time and TTL are kept, and it expires when the entry
does, not after this store’s default TTL. A store may hold it for less, as a hybrid store’s
local layer does for local.ttl_secs. get_entry from one store and set_entry into
another copies an entry without changing it.Source§async fn remove(&self, key: &str) -> Result<bool, HybridCacheError>
async fn remove(&self, key: &str) -> Result<bool, HybridCacheError>
key, and returns whether it was there.Source§async fn remove_prefix(&self, prefix: &str) -> Result<usize, HybridCacheError>
async fn remove_prefix(&self, prefix: &str) -> Result<usize, HybridCacheError>
prefix, matched by whole levels (user removes user:42, not
users:42, nor the key user itself), and returns how many. Fails with
CacheError::InvalidKey when prefix is empty or has an empty level. Read moreSource§async fn clear(&self) -> Result<(), HybridCacheError>
async fn clear(&self) -> Result<(), HybridCacheError>
Source§fn get<CV>(
&self,
key: &str,
) -> impl Future<Output = Result<Option<CV>, Self::Error>> + Sendwhere
CV: CacheValue,
fn get<CV>(
&self,
key: &str,
) -> impl Future<Output = Result<Option<CV>, Self::Error>> + Sendwhere
CV: CacheValue,
key as a CV, or None when it is missing or expired.Source§fn set<CV>(
&self,
key: &str,
value: CV,
options: impl Into<Option<CacheOptions>> + Send,
) -> impl Future<Output = Result<(), Self::Error>> + Sendwhere
CV: CacheValue,
fn set<CV>(
&self,
key: &str,
value: CV,
options: impl Into<Option<CacheOptions>> + Send,
) -> impl Future<Output = Result<(), Self::Error>> + Sendwhere
CV: CacheValue,
value under key, replacing what is there. options sets this write’s TTL;
None uses the store’s default TTL. Fails when the TTL is over 365 days. Read moreSource§fn get_or_set<CV, F, Fut, E>(
&self,
key: &str,
load: F,
options: impl Into<Option<CacheOptions>> + Send,
) -> impl Future<Output = Result<CV, E>> + Send
fn get_or_set<CV, F, Fut, E>( &self, key: &str, load: F, options: impl Into<Option<CacheOptions>> + Send, ) -> impl Future<Output = Result<CV, E>> + Send
key, or runs load when there is none, then stores and returns
what it gives. Of the callers on this store and its clones, one per key runs load; the
others wait for it and get what it stored, or after lock_timeout_ms run load too. Other
stores, such as those in other processes, load on their own, and a write made while load
runs can be overwritten by its result. With refresh_threshold set, a value past that
share of its TTL is loaded again by one caller, while the others get the cached value; if
that load fails, its caller gets the cached value as long as the store still holds it. Read moreSource§impl<D, C> Clone for HybridCacheStore<D, C>where
D: CacheStore + 'static,
C: Clock,
impl<D, C> Clone for HybridCacheStore<D, C>where
D: CacheStore + 'static,
C: Clock,
Source§fn clone(&self) -> HybridCacheStore<D, C>
fn clone(&self) -> HybridCacheStore<D, C>
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more