Struct Client

pub struct Client { /* private fields */ }

High-level memcached client.

Client is mapped one-to-one with a given connection to a memcached server, and provides a high-level API for executing commands on that connection.

Implementations

impl Client

pub async fn new<S: AsRef<str>>(dsn: S) -> Result<Client, Error>

Creates a new Client based on the given data source string.

Supports UNIX domain sockets and TCP connections. For TCP: the DSN should be in the format of tcp://<IP>:<port> or <IP>:<port>. For UNIX: the DSN should be in the format of unix://<path>.

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

Gets the version of the server.

If the version is retrieved successfully, String is returned containing the version component e.g. 1.6.7, otherwise Error is returned.

For some setups, such as those using Twemproxy, this will return an error as those intermediate proxies do not support the version command.

pub async fn dump_keys(&mut self) -> Result<MetadumpIter<'_>, Error>

Dumps all keys from the server.

This operation scans all slab classes from tail to head, in a non-blocking fashion. Thus, not all items will be found as new items could be inserted or deleted while the crawler is still running.

MetadumpIter must be iterated over to discover whether or not the crawler successfully started, as this call will only return Error if the command failed to be written to the server at all.

Available as of memcached 1.4.31.

pub async fn stats(&mut self) -> Result<FxHashMap<String, String>, Error>

Collects statistics from the server.

The statistics that may be returned are detailed in the protocol specification for memcached, but all values returned by this method are returned as strings and are not further interpreted or validated for conformity.

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

Flushes all existing items on the server

This operation invalidates all existing items immediately. Any items with an update time older than the time of the flush_all operation will be ignored for retrieval purposes. This operation does not free up memory taken up by the existing items.

Trait Implementations

impl AsciiProtocol for Client

async fn delete_no_reply<K>(&mut self, key: K) -> Result<(), Error>

where K: AsRef<[u8]>,

Delete a key but don’t wait for a reply.

async fn delete<K>(&mut self, key: K) -> Result<(), Error>

where K: AsRef<[u8]>,

Delete a key and wait for a reply

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

Gets the given key.

async fn get_multi<I, K>(&mut self, keys: I) -> Result<Vec<Value>, Error>

where I: IntoIterator<Item = K>, K: AsRef<[u8]>,

Gets multiple keys.

async fn get_many<I, K>(&mut self, keys: I) -> Result<Vec<Value>, Error>

where I: IntoIterator<Item = K>, K: AsRef<[u8]>,

👎Deprecated since 0.4.0: This is now an alias for get_multi, and will be removed in the future.

Gets the given keys.

async fn set<K, V>( &mut self, key: K, value: V, ttl: Option<i64>, flags: Option<u32>, ) -> Result<(), Error>

where K: AsRef<[u8]>, V: AsMemcachedValue,

Sets the given key.

async fn set_multi<'a, K, V>( &mut self, kv: &'a [(K, V)], ttl: Option<i64>, flags: Option<u32>, ) -> Result<FxHashMap<&'a K, Result<(), Error>>, Error>

where K: AsRef<[u8]> + Eq + Hash + Debug, V: AsMemcachedValue,

Sets multiple keys and values through pipelined commands.

async fn add<K, V>( &mut self, key: K, value: V, ttl: Option<i64>, flags: Option<u32>, ) -> Result<(), Error>

where K: AsRef<[u8]>, V: AsMemcachedValue,

Add a key. If the value exists, Err(Protocol(NotStored)) is returned.

async fn add_multi<'a, K, V>( &mut self, kv: &'a [(K, V)], ttl: Option<i64>, flags: Option<u32>, ) -> Result<FxHashMap<&'a K, Result<(), Error>>, Error>

where K: AsRef<[u8]> + Eq + Hash + Debug, V: AsMemcachedValue,

Attempts to add multiple keys and values through pipelined commands.

async fn delete_multi_no_reply<K>(&mut self, keys: &[K]) -> Result<(), Error>

where K: AsRef<[u8]>,

Delete multiple keys

async fn increment<K>(&mut self, key: K, amount: u64) -> Result<u64, Error>

where K: AsRef<[u8]>,

Increments the given key by the specified amount. Can overflow from the max value of u64 (18446744073709551615) -> 0. If the key does not exist, the server will return a KeyNotFound error. If the key exists but the value is non-numeric, the server will return a ClientError.

async fn increment_no_reply<K>( &mut self, key: K, amount: u64, ) -> Result<(), Error>

where K: AsRef<[u8]>,

Increments the given key by the specified amount with no reply from the server. Can overflow from the max value of u64 (18446744073709551615) -> 0. Always returns () for a complete request, will not return any indication of success or failure.

async fn decrement<K>(&mut self, key: K, amount: u64) -> Result<u64, Error>

where K: AsRef<[u8]>,

Decrements the given key by the specified amount. Will not decrement the counter below 0. If the key does not exist, the server will return a KeyNotFound error. If the key exists but the value is non-numeric, the server will return a ClientError.

async fn decrement_no_reply<K>( &mut self, key: K, amount: u64, ) -> Result<(), Error>

where K: AsRef<[u8]>,

Decrements the given key by the specified amount with no reply from the server. Will not decrement the counter below 0. Always returns () for a complete request, will not return any indication of success or failure.

impl MetaProtocol for Client

async fn meta_get<K: AsRef<[u8]>>( &mut self, key: K, is_quiet: bool, opaque: Option<&[u8]>, meta_flags: Option<&[&str]>, ) -> Result<Option<MetaValue>, Error>

Gets the given key with additional metadata.

async fn meta_set<K, V>( &mut self, key: K, value: V, is_quiet: bool, opaque: Option<&[u8]>, meta_flags: Option<&[&str]>, ) -> Result<Option<MetaValue>, Error>

where K: AsRef<[u8]>, V: AsMemcachedValue,

Sets the given key with additional metadata.

async fn meta_delete<K: AsRef<[u8]>>( &mut self, key: K, is_quiet: bool, opaque: Option<&[u8]>, meta_flags: Option<&[&str]>, ) -> Result<Option<MetaValue>, Error>

Deletes the given key with additional metadata.

async fn meta_increment<K: AsRef<[u8]>>( &mut self, key: K, is_quiet: bool, opaque: Option<&[u8]>, delta: Option<u64>, meta_flags: Option<&[&str]>, ) -> Result<Option<MetaValue>, Error>

Performs an increment (arithmetic) operation on the given key.

async fn meta_decrement<K: AsRef<[u8]>>( &mut self, key: K, is_quiet: bool, opaque: Option<&[u8]>, delta: Option<u64>, meta_flags: Option<&[&str]>, ) -> Result<Option<MetaValue>, Error>

Performs a decrement (arithmetic) operation on the given key.