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 get<K: AsRef<[u8]>>( &mut self, key: K, ) -> Result<Option<Value>, Error>

Gets the given key.

If the key is found, Some(Value) is returned, describing the metadata and data of the key.

Otherwise, Error is returned.

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

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

Gets the given keys.

If any of the keys are found, a vector of Value will be returned, where Value describes the metadata and data of the key.

Otherwise, Error is returned.

pub 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.

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

pub 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.

If ttl or flags are not specified, they will default to 0. If the value is set successfully, () is returned, otherwise Error is returned.

pub 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.

If ttl or flags are not specified, they will default to 0. The same values for ttl and flags will be applied to each key. Returns a result with a HashMap of keys mapped to the result of the set operation, or an error.

pub 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.

pub 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.

If ttl or flags are not specified, they will default to 0. The same values for ttl and flags will be applied to each key. Returns a result with a HashMap of keys mapped to the result of the add operation, or an error.

pub 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.

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

where K: AsRef<[u8]>,

Delete a key and wait for a reply

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

where K: AsRef<[u8]>,

Delete multiple keys

pub 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.

pub 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.

pub 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.

pub 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.

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.