Trait Cache

Source

pub trait Cache:
    Send
    + Sync
    + 'static {
    // Required methods
    fn driver(&self) -> &'static str;
    fn get<'a>(&'a self, key: &'a str) -> BoxFuture<'a, Result<Option<Json>>>;
    fn put<'a>(
        &'a self,
        key: &'a str,
        value: Json,
        ttl: Duration,
    ) -> BoxFuture<'a, Result<()>>;
    fn forever<'a>(
        &'a self,
        key: &'a str,
        value: Json,
    ) -> BoxFuture<'a, Result<()>>;
    fn forget<'a>(&'a self, key: &'a str) -> BoxFuture<'a, Result<bool>>;
    fn flush(&self) -> BoxFuture<'_, Result<()>>;
    fn increment<'a>(
        &'a self,
        key: &'a str,
        by: i64,
    ) -> BoxFuture<'a, Result<i64>>;
    fn increment_within<'a>(
        &'a self,
        key: &'a str,
        by: i64,
        ttl: Duration,
    ) -> BoxFuture<'a, Result<i64>>;
    fn ttl<'a>(
        &'a self,
        key: &'a str,
    ) -> BoxFuture<'a, Result<Option<Duration>>>;

    // Provided methods
    fn has<'a>(&'a self, key: &'a str) -> BoxFuture<'a, Result<bool>> { ... }
    fn decrement<'a>(
        &'a self,
        key: &'a str,
        by: i64,
    ) -> BoxFuture<'a, Result<i64>> { ... }
    fn pull<'a>(&'a self, key: &'a str) -> BoxFuture<'a, Result<Option<Json>>> { ... }
}

Expand description

A cache backend.

Values are Json rather than a generic T for two reasons: it keeps the trait dyn-compatible, and every rustlavel package already speaks Json, so anything that can be serialised can be cached without a second trait.

Required Methods§

Source

fn driver(&self) -> &'static str

The driver’s name, used in cache.hit / cache.miss events and in error messages. Telescope shows it as the store column.

Source

fn get<'a>(&'a self, key: &'a str) -> BoxFuture<'a, Result<Option<Json>>>

Fetch a value, or None when it is missing or expired.

Expiry is checked on read in every driver, so an entry that nobody asks for again is never reported as present, even before a sweep removes it.

Source

fn put<'a>( &'a self, key: &'a str, value: Json, ttl: Duration, ) -> BoxFuture<'a, Result<()>>

Store a value that expires after ttl.

A zero or negative ttl is treated as “already expired”: the key is forgotten rather than stored, which matches Laravel and avoids leaving an entry behind that no read will ever return.

Source

fn forever<'a>(&'a self, key: &'a str, value: Json) -> BoxFuture<'a, Result<()>>

Store a value with no expiry. It still goes away on Cache::flush.

Source

fn forget<'a>(&'a self, key: &'a str) -> BoxFuture<'a, Result<bool>>

Remove a key. Returns whether something was actually there.

Source

fn flush(&self) -> BoxFuture<'_, Result<()>>

Remove everything this store owns.

Source

fn increment<'a>(&'a self, key: &'a str, by: i64) -> BoxFuture<'a, Result<i64>>

Add by to a counter, creating it at zero first. Returns the new value.

Counters are stored as plain JSON numbers so get on a counter returns something sensible in every driver.

Source

fn increment_within<'a>( &'a self, key: &'a str, by: i64, ttl: Duration, ) -> BoxFuture<'a, Result<i64>>

Increment a counter, giving it ttl only when this call created it.

Rate limiting needs exactly this and nothing weaker: the first request of a window starts the clock, and the ninety-ninth must not restart it. Built as a driver method rather than a get-then-put in the limiter because a read-modify-write loses counts under concurrency, which is the one thing a rate limiter may not do.

Source