KvClient

d_engine

Trait KvClient 

Source 
pub trait KvClient: Send + Sync {
    // Required methods
    fn put<'life0, 'async_trait>(
        &'life0 self,
        key: impl AsRef<[u8]> + Send + 'async_trait,
        value: impl AsRef<[u8]> + Send + 'async_trait,
    ) -> Pin<Box<dyn Future<Output = Result<(), KvClientError>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             Self: 'async_trait;
    fn put_with_ttl<'life0, 'async_trait>(
        &'life0 self,
        key: impl AsRef<[u8]> + Send + 'async_trait,
        value: impl AsRef<[u8]> + Send + 'async_trait,
        ttl_secs: u64,
    ) -> Pin<Box<dyn Future<Output = Result<(), KvClientError>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             Self: 'async_trait;
    fn get<'life0, 'async_trait>(
        &'life0 self,
        key: impl AsRef<[u8]> + Send + 'async_trait,
    ) -> Pin<Box<dyn Future<Output = Result<Option<Bytes>, KvClientError>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             Self: 'async_trait;
    fn get_multi<'life0, 'life1, 'async_trait>(
        &'life0 self,
        keys: &'life1 [Bytes],
    ) -> Pin<Box<dyn Future<Output = Result<Vec<Option<Bytes>>, KvClientError>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             Self: 'async_trait;
    fn delete<'life0, 'async_trait>(
        &'life0 self,
        key: impl AsRef<[u8]> + Send + 'async_trait,
    ) -> Pin<Box<dyn Future<Output = Result<(), KvClientError>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             Self: 'async_trait;
}
Expand description

Unified key-value store interface.

This trait abstracts over different client implementations, allowing applications to write generic code that works with both remote (gRPC) and embedded (local) access.

§Consistency Guarantees

  • put(): Strong consistency, linearizable writes
  • get(): Linearizable reads by default
  • delete(): Strong consistency, linearizable deletes

§Thread Safety

All implementations must be Send + Sync, safe for concurrent access.

§Performance Characteristics

  • GrpcKvClient: 1-2ms latency (network + serialization)
  • LocalKvClient: <0.1ms latency (direct function call)

Required Methods§

Source

fn put<'life0, 'async_trait>( &'life0 self, key: impl AsRef<[u8]> + Send + 'async_trait, value: impl AsRef<[u8]> + Send + 'async_trait, ) -> Pin<Box<dyn Future<Output = Result<(), KvClientError>> + Send + 'async_trait>>
where 'life0: 'async_trait, Self: 'async_trait,

Stores a key-value pair with strong consistency.

The write is replicated to a quorum of nodes before returning, ensuring durability and linearizability.

§Arguments
  • key - The key to store (arbitrary bytes)
  • value - The value to store (arbitrary bytes)
§Errors
§Example
ⓘ
client.put(b"user:1001", b"Alice").await?;
Source

fn put_with_ttl<'life0, 'async_trait>( &'life0 self, key: impl AsRef<[u8]> + Send + 'async_trait, value: impl AsRef<[u8]> + Send + 'async_trait, ttl_secs: u64, ) -> Pin<Box<dyn Future<Output = Result<(), KvClientError>> + Send + 'async_trait>>
where 'life0: 'async_trait, Self: 'async_trait,

Stores a key-value pair with time-to-live (TTL).

The key will automatically expire after ttl_secs seconds.

§Arguments
  • key - The key to store
  • value - The value to store
  • ttl_secs - Time-to-live in seconds
§Errors

Same as put()

§Example
ⓘ
// Session expires after 1 hour
client.put_with_ttl(b"session:abc", b"user_data", 3600).await?;
Source

fn get<'life0, 'async_trait>( &'life0 self, key: impl AsRef<[u8]> + Send + 'async_trait, ) -> Pin<Box<dyn Future<Output = Result<Option<Bytes>, KvClientError>> + Send + 'async_trait>>
where 'life0: 'async_trait, Self: 'async_trait,

Retrieves the value associated with a key.

Uses linearizable reads by default, ensuring the returned value reflects all previously committed writes.

§Arguments
  • key - The key to retrieve
§Returns
  • Ok(Some(value)) if key exists
  • Ok(None) if key does not exist or has expired
  • Err(_) if operation failed
§Errors
§Example
ⓘ
match client.get(b"user:1001").await? {
    Some(value) => println!("User: {:?}", value),
    None => println!("User not found"),
}
Source

fn get_multi<'life0, 'life1, 'async_trait>( &'life0 self, keys: &'life1 [Bytes], ) -> Pin<Box<dyn Future<Output = Result<Vec<Option<Bytes>>, KvClientError>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Retrieves multiple keys in a single request.

More efficient than multiple individual get() calls when fetching multiple keys, as it batches the requests.

§Arguments
  • keys - Slice of keys to retrieve
§Returns

Vector of results in the same order as input keys. None for keys that don’t exist.

§Errors

Same as get()

§Example
ⓘ
let keys = vec![
    Bytes::from("user:1001"),
    Bytes::from("user:1002"),
];
let results = client.get_multi(&keys).await?;
Source

fn delete<'life0, 'async_trait>( &'life0 self, key: impl AsRef<[u8]> + Send + 'async_trait, ) -> Pin<Box<dyn Future<Output = Result<(), KvClientError>> + Send + 'async_trait>>
where 'life0: 'async_trait, Self: 'async_trait,

Deletes a key-value pair with strong consistency.

The deletion is replicated to a quorum before returning. Returns successfully even if the key does not exist (idempotent).

§Arguments
  • key - The key to delete
§Errors
§Example
ⓘ
client.delete(b"temp:session_123").await?;

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§