Struct cache::persistent::client::Client

source ·

pub struct Client { /* private fields */ }

Expand description

A gRPC cache client.

The semantics of the Client API are the same as those of the NamespaceCache API.

Implementations§

source §

impl Client

source

pub fn with_default_config(kind: ClientKind, url: impl Into<String>) -> Self

Creates a new gRPC cache client for a server at url with default configuration values.

source

pub fn builder() -> ClientBuilder

Creates a new gRPC cache client.

source

pub fn local(url: impl Into<String>) -> ClientBuilder

Creates a new local gRPC cache client.

See ClientKind for an explanation of the different kinds of clients.

source

pub fn remote(url: impl Into<String>) -> ClientBuilder

Creates a new remote gRPC cache client.

See ClientKind for an explanation of the different kinds of clients.

source

pub fn generate<K: Serialize + Any + Send + Sync, V: Serialize + DeserializeOwned + Send + Sync + Any>( &self, namespace: impl Into<Namespace>, key: K, generate_fn: impl GenerateFn<K, V> ) -> CacheHandle<V>

Ensures that a value corresponding to key is generated, using generate_fn to generate it if it has not already been generated.

Returns a handle to the value. If the value is not yet generated, it is generated in the background.

For more detailed examples, refer to NamespaceCache::generate.

§Examples

use cache::{persistent::client::{Client, ClientKind}, error::Error, Cacheable};

let client = Client::with_default_config(ClientKind::Local, "http://127.0.0.1:28055");

fn generate_fn(tuple: &(u64, u64)) -> u64 {
    tuple.0 + tuple.1
}

let handle = client.generate("example.namespace", (5, 6), generate_fn);
assert_eq!(*handle.get(), 11);

source

pub fn generate_with_state<K: Serialize + Send + Sync + Any, V: Serialize + DeserializeOwned + Send + Sync + Any, S: Send + Sync + Any>( &self, namespace: impl Into<Namespace>, key: K, state: S, generate_fn: impl GenerateWithStateFn<K, S, V> ) -> CacheHandle<V>

Ensures that a value corresponding to key is generated, using generate_fn to generate it if it has not already been generated.

Returns a handle to the value. If the value is not yet generated, it is generated in the background.

For more detailed examples, refer to NamespaceCache::generate_with_state.

§Examples

use std::sync::{Arc, Mutex};
use cache::{persistent::client::{Client, ClientKind}, error::Error, Cacheable};

#[derive(Clone)]
pub struct Log(Arc<Mutex<Vec<(u64, u64)>>>);

let client = Client::with_default_config(ClientKind::Local, "http://127.0.0.1:28055");
let log = Log(Arc::new(Mutex::new(Vec::new())));

fn generate_fn(tuple: &(u64, u64), state: Log) -> u64 {
    println!("Logging parameters...");
    state.0.lock().unwrap().push(*tuple);
    tuple.0 + tuple.1
}

let handle = client.generate_with_state(
    "example.namespace", (5, 6), log.clone(), generate_fn
);
assert_eq!(*handle.get(), 11);
assert_eq!(log.0.lock().unwrap().clone(), vec![(5, 6)]);

source

pub fn generate_result<K: Serialize + Any + Send + Sync, V: Serialize + DeserializeOwned + Send + Sync + Any, E: Send + Sync + Any>( &self, namespace: impl Into<Namespace>, key: K, generate_fn: impl GenerateResultFn<K, V, E> ) -> CacheHandle<Result<V, E>>

Ensures that a result corresponding to key is generated, using generate_fn to generate it if it has not already been generated.

Does not cache on failure as errors are not constrained to be serializable/deserializable. As such, failures should happen quickly, or should be serializable and stored as part of cached value using Client::generate.

Returns a handle to the value. If the value is not yet generated, it is generated in the background.

For more detailed examples, refer to NamespaceCache::generate_result.

§Examples

use cache::{persistent::client::{Client, ClientKind}, error::Error, Cacheable};

let client = Client::with_default_config(ClientKind::Local, "http://127.0.0.1:28055");

fn generate_fn(tuple: &(u64, u64)) -> anyhow::Result<u64> {
    if *tuple == (5, 5) {
        Err(anyhow::anyhow!("invalid tuple"))
    } else {
        Ok(tuple.0 + tuple.1)
    }
}

let handle = client.generate_result("example.namespace", (5, 5), generate_fn);
assert_eq!(format!("{}", handle.unwrap_err_inner().root_cause()), "invalid tuple");

source

pub fn generate_result_with_state<K: Serialize + Send + Sync + Any, V: Serialize + DeserializeOwned + Send + Sync + Any, E: Send + Sync + Any, S: Send + Sync + Any>( &self, namespace: impl Into<Namespace>, key: K, state: S, generate_fn: impl GenerateResultWithStateFn<K, S, V, E> ) -> CacheHandle<Result<V, E>>

Ensures that a value corresponding to key is generated, using generate_fn to generate it if it has not already been generated.

Does not cache on failure as errors are not constrained to be serializable/deserializable. As such, failures should happen quickly, or should be serializable and stored as part of cached value using Client::generate_with_state.

Returns a handle to the value. If the value is not yet generated, it is generated in the background.

For more detailed examples, refer to NamespaceCache::generate_result_with_state.

§Examples

use std::sync::{Arc, Mutex};
use cache::{persistent::client::{Client, ClientKind}, error::Error, Cacheable};

#[derive(Clone)]
pub struct Log(Arc<Mutex<Vec<(u64, u64)>>>);

let client = Client::with_default_config(ClientKind::Local, "http://127.0.0.1:28055");
let log = Log(Arc::new(Mutex::new(Vec::new())));

fn generate_fn(tuple: &(u64, u64), state: Log) -> anyhow::Result<u64> {
    println!("Logging parameters...");
    state.0.lock().unwrap().push(*tuple);

    if *tuple == (5, 5) {
        Err(anyhow::anyhow!("invalid tuple"))
    } else {
        Ok(tuple.0 + tuple.1)
    }
}

let handle = client.generate_result_with_state(
    "example.namespace", (5, 5), log.clone(), generate_fn,
);
assert_eq!(format!("{}", handle.unwrap_err_inner().root_cause()), "invalid tuple");
assert_eq!(log.0.lock().unwrap().clone(), vec![(5, 5)]);

source

pub fn get<K: Cacheable>( &self, namespace: impl Into<Namespace>, key: K ) -> CacheHandle<Result<K::Output, K::Error>>

Gets a handle to a cacheable object from the cache, generating the object in the background if needed.

Does not cache errors, so any errors thrown should be thrown quickly. Any errors that need to be cached should be included in the cached output or should be cached using Client::get_with_err.

For more detailed examples, refer to NamespaceCache::get.

§Examples

use cache::{persistent::client::{Client, ClientKind}, error::Error, Cacheable};
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize, Hash, Eq, PartialEq)]
pub struct Params {
    param1: u64,
    param2: String,
};

impl Cacheable for Params {
    type Output = u64;
    type Error = anyhow::Error;

    fn generate(&self) -> anyhow::Result<u64> {
        Ok(2 * self.param1)
    }
}

let client = Client::with_default_config(ClientKind::Local, "http://127.0.0.1:28055");

let handle = client.get(
    "example.namespace", Params { param1: 50, param2: "cache".to_string() }
);
assert_eq!(*handle.unwrap_inner(), 100);

source

pub fn get_with_err<E: Send + Sync + Serialize + DeserializeOwned + Any, K: Cacheable<Error = E>>( &self, namespace: impl Into<Namespace>, key: K ) -> CacheHandle<Result<K::Output, K::Error>>

Gets a handle to a cacheable object from the cache, caching failures as well.

Generates the object in the background if needed.

For more detailed examples, refer to NamespaceCache::get_with_err.

§Examples

use cache::{persistent::client::{Client, ClientKind}, error::Error, Cacheable};
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize, Hash, Eq, PartialEq)]
pub struct Params {
    param1: u64,
    param2: String,
};

impl Cacheable for Params {
    type Output = u64;
    type Error = String;

    fn generate(&self) -> Result<Self::Output, Self::Error> {
        if self.param1 == 5 {
            Err("invalid param".to_string())
        } else {
            Ok(2 * self.param1)
        }
    }
}

let client = Client::with_default_config(ClientKind::Local, "http://127.0.0.1:28055");

let handle = client.get_with_err(
    "example.namespace", Params { param1: 5, param2: "cache".to_string() }
);
assert_eq!(handle.unwrap_err_inner(), "invalid param");

source

pub fn get_with_state<S: Send + Sync + Any, K: CacheableWithState<S>>( &self, namespace: impl Into<Namespace>, key: K, state: S ) -> CacheHandle<Result<K::Output, K::Error>>

Gets a handle to a cacheable object from the cache, generating the object in the background if needed.

Does not cache errors, so any errors thrown should be thrown quickly. Any errors that need to be cached should be included in the cached output or should be cached using Client::get_with_state_and_err.

For more detailed examples, refer to NamespaceCache::get_with_state.

§Examples

use std::sync::{Arc, Mutex};
use cache::{persistent::client::{Client, ClientKind}, error::Error, CacheableWithState};
use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize, Serialize, Clone, Hash, Eq, PartialEq)]
pub struct Params(u64);

#[derive(Clone)]
pub struct Log(Arc<Mutex<Vec<Params>>>);

impl CacheableWithState<Log> for Params {
    type Output = u64;
    type Error = anyhow::Error;

    fn generate_with_state(&self, state: Log) -> anyhow::Result<u64> {
        println!("Logging parameters...");
        state.0.lock().unwrap().push(self.clone());
        Ok(2 * self.0)
    }
}

let client = Client::with_default_config(ClientKind::Local, "http://127.0.0.1:28055");
let log = Log(Arc::new(Mutex::new(Vec::new())));

let handle = client.get_with_state(
    "example.namespace",
    Params(0),
    log.clone(),
);
assert_eq!(*handle.unwrap_inner(), 0);
assert_eq!(log.0.lock().unwrap().clone(), vec![Params(0)]);