Skip to main content

HybridCacheStore

Struct HybridCacheStore 

Source
pub struct HybridCacheStore<D, C = SystemClock>
where D: CacheStore + 'static, C: Clock,
{ /* private fields */ }
Available on crate feature 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,

Source

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,

Source

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.

Source

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.

Source

pub fn local_reads_enabled(&self) -> bool

Whether reads use the local layer: only while the backplane worker is subscribed.

Source

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>

Source

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,

Source§

type Error = HybridCacheError

What the store’s calls fail with. Every CacheError converts into it.
Source§

fn name(&self) -> &KeyPrefix

The store’s name, written in front of every key it stores.
Source§

fn cache_settings(&self) -> &CacheSettings

The store’s TTL, refresh-ahead and lock settings. A hybrid store returns its own, which both of its layers follow.
Source§

async fn get_entry<CV>( &self, key: &str, ) -> Result<Option<CacheEntry<CV>>, HybridCacheError>
where CV: CacheValue,

The entry under 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,

Stores 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>

Removes key, and returns whether it was there.
Source§

async fn remove_prefix(&self, prefix: &str) -> Result<usize, HybridCacheError>

Removes every key under 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 more
Source§

async fn clear(&self) -> Result<(), HybridCacheError>

Removes every key in this store, and nothing outside it.
Source§

fn get<CV>( &self, key: &str, ) -> impl Future<Output = Result<Option<CV>, Self::Error>> + Send
where CV: CacheValue,

The value under 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>> + Send
where CV: CacheValue,

Stores 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 more
Source§

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
where CV: CacheValue, F: FnOnce() -> Fut + Send, Fut: Future<Output = Result<CV, E>> + Send, E: Send,

Returns the value under 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 more
Source§

impl<D, C> Clone for HybridCacheStore<D, C>
where D: CacheStore + 'static, C: Clock,

Source§

fn clone(&self) -> HybridCacheStore<D, C>

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl<D, C> Debug for HybridCacheStore<D, C>
where D: CacheStore + 'static, C: Clock,

Source§

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<D, C = SystemClock> !RefUnwindSafe for HybridCacheStore<D, C>

§

impl<D, C = SystemClock> !UnwindSafe for HybridCacheStore<D, C>

§

impl<D, C> Freeze for HybridCacheStore<D, C>
where Arc<D>: Freeze, Arc<State<C>>: Freeze,

§

impl<D, C> Send for HybridCacheStore<D, C>
where Arc<D>: Send, Arc<State<C>>: Send,

§

impl<D, C> Sync for HybridCacheStore<D, C>
where Arc<D>: Sync, Arc<State<C>>: Sync,

§

impl<D, C> Unpin for HybridCacheStore<D, C>
where Arc<D>: Unpin, Arc<State<C>>: Unpin,

§

impl<D, C> UnsafeUnpin for HybridCacheStore<D, C>
where Arc<D>: UnsafeUnpin, Arc<State<C>>: UnsafeUnpin,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> FutureExt for T

Source§

fn with_context(self, otel_cx: Context) -> WithContext<Self> ⓘ

Attaches the provided Context to this type, returning a WithContext wrapper. Read more
Source§

fn with_current_context(self) -> WithContext<Self> ⓘ

Attaches the current Context to this type, returning a WithContext wrapper. Read more
Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more