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
impl CacheClient
Sourcepub fn builder(client: Client) -> CacheClientBuilder
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();Sourcepub fn client(&self) -> &Client
pub fn client(&self) -> &Client
The wrapped Client, for operations that should never involve the cache.
Sourcepub fn last_known_revision(&self) -> Option<Revision>
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.
Sourcepub fn coherent_revision(&self, range: impl AsRange) -> Option<Revision>
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.
Sourcepub fn get(&self, key: impl AsKey) -> Get<Self>
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());
}Sourcepub fn put(&self, key: impl AsKey) -> Put<Self, ()>
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.
Sourcepub fn delete(&self, key: impl AsKey) -> Delete<Self, bool>
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.
Sourcepub fn delete_range(&self, range: impl AsRange) -> Delete<Self, usize>
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.
Sourcepub fn delete_prefix(&self, prefix: impl AsKey) -> Delete<Self, usize>
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.
Sourcepub fn list(&self, query: impl AsRange) -> List<Self, Record>
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.
Sourcepub fn list_prefix(&self, prefix: impl AsKey) -> List<Self, Record>
pub fn list_prefix(&self, prefix: impl AsKey) -> List<Self, Record>
Sourcepub fn transaction(&self) -> Transaction<Self>
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.
Trait Implementations§
Source§impl Clone for CacheClient
impl Clone for CacheClient
Source§impl KvDriver for CacheClient
impl KvDriver for CacheClient
Source§type GetFuture = CacheFuture<GetFuture>
type GetFuture = CacheFuture<GetFuture>
execute_get.Source§type PutFuture<R> = CacheFuture<PutFuture<Result<PutResponse<R>, PutError>>>
type PutFuture<R> = CacheFuture<PutFuture<Result<PutResponse<R>, PutError>>>
execute_put.Source§type DeleteFuture<R, P> = CacheFuture<DeleteFuture<Result<DeleteResponse<R, P>, DeleteError>>>
type DeleteFuture<R, P> = CacheFuture<DeleteFuture<Result<DeleteResponse<R, P>, DeleteError>>>
execute_delete.Source§type ListView<R> = CacheListView<R>
type ListView<R> = CacheListView<R>
Source§type ListViewFuture<R> = CacheFuture<ListFuture<Result<ListView<R>, GetError>>, Result<CacheListView<R>, GetError>>
type ListViewFuture<R> = CacheFuture<ListFuture<Result<ListView<R>, GetError>>, Result<CacheListView<R>, GetError>>
Source§type CountFuture = CacheFuture<ListFuture<Result<CountResponse, GetError>>>
type CountFuture = CacheFuture<ListFuture<Result<CountResponse, GetError>>>
execute_count.Source§type CommitFuture = CacheFuture<TransactionFuture>
type CommitFuture = CacheFuture<TransactionFuture>
execute_transaction.Source§type CompactFuture = CacheFuture<CompactFuture>
type CompactFuture = CacheFuture<CompactFuture>
execute_compact.Source§fn execute_delete<R, P>(
self,
delete: Delete<(), R, P>,
) -> Self::DeleteFuture<R, P>
fn execute_delete<R, P>( self, delete: Delete<(), R, P>, ) -> Self::DeleteFuture<R, P>
Source§fn execute_list_records(
self,
list: List<(), Record>,
) -> Self::ListViewFuture<Record>
fn execute_list_records( self, list: List<(), Record>, ) -> Self::ListViewFuture<Record>
Source§fn execute_list_keys(
self,
list: List<(), KeyWithMetadata>,
) -> Self::ListViewFuture<KeyWithMetadata>
fn execute_list_keys( self, list: List<(), KeyWithMetadata>, ) -> Self::ListViewFuture<KeyWithMetadata>
Source§fn execute_count(self, list: List<(), usize>) -> Self::CountFuture
fn execute_count(self, list: List<(), usize>) -> Self::CountFuture
Source§fn execute_transaction(self, txn: Transaction<()>) -> Self::CommitFuture
fn execute_transaction(self, txn: Transaction<()>) -> Self::CommitFuture
Source§fn execute_compact(self, compact: Compact<()>) -> Self::CompactFuture
fn execute_compact(self, compact: Compact<()>) -> Self::CompactFuture
Auto Trait Implementations§
impl !RefUnwindSafe for CacheClient
impl !UnwindSafe for CacheClient
impl Freeze for CacheClient
impl Send for CacheClient
impl Sync for CacheClient
impl Unpin for CacheClient
impl UnsafeUnpin for CacheClient
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoRequest<T> for T
impl<T> IntoRequest<T> for T
Source§fn into_request(self) -> Request<T>
fn into_request(self) -> Request<T>
T in a tonic::Request