Struct ShardedClient 

pub struct ShardedClient { /* private fields */ }

A ketama-sharded Memcache client.

Commands are routed to independent Memcache instances using consistent hashing. Each server has a pool of connections with round-robin dispatch and lazy reconnection.

Retry semantics (at-least-once)

When a send succeeds but the connection dies before the response is read, the command is retried on another connection. The server may have executed the first attempt, so commands are at-least-once: harmless for idempotent operations (GET/SET/DEL), but non-idempotent commands (INCR/DECR/APPEND/PREPEND/CAS/ADD) can be applied twice under connection churn. Wrap such operations in application-level idempotency (unique keys, versioning) if double-execution matters.

Implementations

impl ShardedClient

pub fn new(config: ShardedConfig) -> Self

Create a new sharded client. All connections start disconnected.

pub async fn connect_all(&mut self) -> Result<(), Error>

Eagerly connect all connections on all shards.

pub fn close_all(&mut self)

Close all connections on all shards.

pub fn shard_count(&self) -> usize

Number of shards (servers).

pub async fn shard_client(&mut self, index: usize) -> Result<Client, Error>

Get a Client for a specific shard by index (for node-level commands).

The returned Client borrows a slot’s connection but the ShardedClient no longer observes its outcome — if the caller hits Error::ConnectionClosed on that client, no slot is marked dead, and subsequent calls (including via ShardedClient::get) may keep hitting the same broken slot until reconnected explicitly. Prefer routed commands when possible.

pub async fn get( &mut self, key: impl AsRef<[u8]>, ) -> Result<Option<Value>, Error>

Get the value of a key. Returns None on cache miss.

pub async fn gets(&mut self, keys: &[&[u8]]) -> Result<Vec<GetValue>, Error>

Get values for multiple keys. All keys must route to the same shard. Returns only hits, each with its key and CAS token.

pub async fn set( &mut self, key: impl AsRef<[u8]>, value: impl AsRef<[u8]>, ) -> Result<(), Error>

Set a key-value pair with default flags (0) and no expiration.

pub async fn set_with_options( &mut self, key: impl AsRef<[u8]>, value: impl AsRef<[u8]>, flags: u32, exptime: u32, ) -> Result<(), Error>

Set a key-value pair with custom flags and expiration time.

pub async fn add( &mut self, key: impl AsRef<[u8]>, value: impl AsRef<[u8]>, ) -> Result<bool, Error>

Store a key only if it does not already exist (ADD command). Returns true if stored, false if the key already exists.

pub async fn replace( &mut self, key: impl AsRef<[u8]>, value: impl AsRef<[u8]>, ) -> Result<bool, Error>

Store a key only if it already exists (REPLACE command). Returns true if stored, false if the key does not exist.

pub async fn incr( &mut self, key: impl AsRef<[u8]>, delta: u64, ) -> Result<Option<u64>, Error>

Increment a numeric value by delta. Returns the new value after incrementing. Returns None if the key does not exist.

pub async fn decr( &mut self, key: impl AsRef<[u8]>, delta: u64, ) -> Result<Option<u64>, Error>

Decrement a numeric value by delta. Returns the new value after decrementing. Returns None if the key does not exist.

pub async fn append( &mut self, key: impl AsRef<[u8]>, value: impl AsRef<[u8]>, ) -> Result<bool, Error>

Append data to an existing item’s value. Returns true if stored, false if the key does not exist.

pub async fn prepend( &mut self, key: impl AsRef<[u8]>, value: impl AsRef<[u8]>, ) -> Result<bool, Error>

Prepend data to an existing item’s value. Returns true if stored, false if the key does not exist.

pub async fn cas( &mut self, key: impl AsRef<[u8]>, value: impl AsRef<[u8]>, cas_unique: u64, ) -> Result<bool, Error>

Compare-and-swap: store the value only if the CAS token matches. Returns Ok(true) if stored, Ok(false) if the CAS token didn’t match (EXISTS), or Err if the key was not found or another error occurred.

pub async fn delete(&mut self, key: impl AsRef<[u8]>) -> Result<bool, Error>

Delete a key. Returns true if deleted, false if not found.

pub async fn flush_all(&mut self) -> Result<(), Error>

Flush all items on all shards.

On a shard whose currently selected slot returns Error::ConnectionClosed, the slot is marked disconnected and the next slot is tried — the previous implementation called Client::new(conn).flush_all() on a conn borrowed from get_conn and never propagated the broken-conn signal back, so a dead slot would remain Connected and every subsequent flush_all (or any other op) would land on the same dead slot.

pub async fn version(&mut self) -> Result<Box<str>, Error>

Get the version string from any connected shard.

As with Self::flush_all, a Error::ConnectionClosed from the inner call marks the slot disconnected and falls through to the next slot / shard rather than leaving a dead slot wedged in the Connected state.