Skip to main content

CacheClient

Struct CacheClient 

Source
pub struct CacheClient(/* private fields */);
Expand description

A caching wrapper around Client that serves reads of configured key ranges from a local, watch-maintained, in-memory store.

Configure the ranges to cache with builder, then use the cache like a client. Reads of keys outside the configured ranges — and reads the cache cannot prove are fresh — transparently pass through to the server, so a read through the cache is never slower than one through the wrapped Client.

Handles are cheap to clone and share one cache. Dropping the last handle stops the background coherence task, which cancels its watches.

See the module-level documentation for the coherence model.

Implementations§

Source§

impl CacheClient

Source

pub fn builder(client: Client) -> CacheClientBuilder

Start building a cache backed by client.

let cache = etcdrs_util::cache::CacheClient::builder(client)
    .cache(etcdrs::Prefix("config/"))
    .cache("leader")
    .build();
Source

pub fn client(&self) -> &Client

The wrapped Client, for operations that should never involve the cache.

Source

pub fn last_known_revision(&self) -> Option<Revision>

The highest store revision observed through this cache, or None if nothing has been observed yet.

Every response header seen by this cache — from operations executed through it, from seed snapshots, and from the watch’s progress notifications — advances this value, as does the revision of every watch event. It never decreases.

Source

pub fn coherent_revision(&self, range: impl AsRange) -> Option<Revision>

The revision the cached contents of range are exact as of.

Returns None if range is not one of the configured cache ranges (compared by exact boundaries, so e.g. Prefix("a/") only matches a range cached as that same prefix) or if it is not seeded: it has not been listed yet, it could not be listed, or etcd refused to watch it, and no retry has listed it since.

Source

pub fn get(&self, key: impl AsKey) -> Get<Self>

Get the record associated with a key.

Served from the local store when the key lies in a configured range that can prove freshness; otherwise the read passes through to the server. Revision-pinned gets (at_revision) always pass through, since the cache holds only the latest values.

let response = cache.get("my-key").await.unwrap();
if let Some(record) = response.record() {
    println!("value: {:?}", record.value());
}
Source

pub fn put(&self, key: impl AsKey) -> Put<Self, ()>

Put a value for a key.

Always executed on the server. The cache never applies writes locally — the change becomes visible through the watch — but the response’s revision immediately gates cached reads, so a get issued after this put resolves will never observe the pre-put value.

Source

pub fn delete(&self, key: impl AsKey) -> Delete<Self, bool>

Delete a single key. Always executed on the server; see put for how writes interact with the cache.

Source

pub fn delete_range(&self, range: impl AsRange) -> Delete<Self, usize>

Delete a range of keys. Always executed on the server; see put for how writes interact with the cache.

Source

pub fn delete_prefix(&self, prefix: impl AsKey) -> Delete<Self, usize>

Delete all keys with the given prefix. Always executed on the server; see put for how writes interact with the cache.

Source

pub fn list(&self, query: impl AsRange) -> List<Self, Record>

List the records within a range.

Served from the local store when the query is fully contained in a single configured range that can prove freshness; otherwise it passes through to the server. Revision-pinned lists always pass through.

Source

pub fn list_prefix(&self, prefix: impl AsKey) -> List<Self, Record>

List the records associated with a prefix.

This is the same as calling list with a Prefix query.

Source

pub fn transaction(&self) -> Transaction<Self>

Begin a transaction. Always executed on the server, including any read operations it contains; see put for how writes interact with the cache.

Source

pub fn compact(&self, revision: Revision) -> Compact<Self>

Compact the store’s history up to revision. Always executed on the server. If compaction outruns a cached range’s watch, the coherence task recovers by taking a fresh snapshot.

Trait Implementations§

Source§

impl Clone for CacheClient

Source§

fn clone(&self) -> Self

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 KvDriver for CacheClient

Source§

type GetFuture = CacheFuture<GetFuture>

The future returned by execute_get.
Source§

type PutFuture<R> = CacheFuture<PutFuture<Result<PutResponse<R>, PutError>>>

The future returned by execute_put.
Source§

type DeleteFuture<R, P> = CacheFuture<DeleteFuture<Result<DeleteResponse<R, P>, DeleteError>>>

The future returned by execute_delete.
Source§

type ListView<R> = CacheListView<R>

The view returned by list operations.
Source§

type ListViewFuture<R> = CacheFuture<ListFuture<Result<ListView<R>, GetError>>, Result<CacheListView<R>, GetError>>

The future returned by list operations.
Source§

type CountFuture = CacheFuture<ListFuture<Result<CountResponse, GetError>>>

The future returned by execute_count.
Source§

type CommitFuture = CacheFuture<TransactionFuture>

The future returned by execute_transaction.
Source§

type CompactFuture = CacheFuture<CompactFuture>

The future returned by execute_compact.
Source§

fn execute_get(self, get: Get<()>) -> Self::GetFuture

Execute a get operation.
Source§

fn execute_put<R>(self, put: Put<(), R>) -> Self::PutFuture<R>

Execute a put operation.
Source§

fn execute_delete<R, P>( self, delete: Delete<(), R, P>, ) -> Self::DeleteFuture<R, P>

Execute a delete operation.
Source§

fn execute_list_records( self, list: List<(), Record>, ) -> Self::ListViewFuture<Record>

Execute a list operation that returns full records (key + value + metadata).
Source§

fn execute_list_keys( self, list: List<(), KeyWithMetadata>, ) -> Self::ListViewFuture<KeyWithMetadata>

Execute a list operation that returns keys with metadata only (no values).
Source§

fn execute_count(self, list: List<(), usize>) -> Self::CountFuture

Execute a count-only list operation.
Source§

fn execute_transaction(self, txn: Transaction<()>) -> Self::CommitFuture

Execute a transaction.
Source§

fn execute_compact(self, compact: Compact<()>) -> Self::CompactFuture

Execute a compaction operation.

Auto Trait Implementations§

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> 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> IntoRequest<T> for T

Source§

fn into_request(self) -> Request<T>

Wrap the input message T in a tonic::Request
Source§

impl<L> LayerExt<L> for L

Source§

fn named_layer<S>(&self, service: S) -> Layered<<L as Layer<S>>::Service, S>
where L: Layer<S>,

Applies the layer to a service and wraps it in Layered.
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