Refreshable

Documentation

A simple wrapper around a value that changes over time.

License

This repository is made available under the Apache 2.0 License.

lib.rs:

A simple wrapper around a value that changes over time.

A Refreshable provides access to both the current value and also ways to be notified of changes made in the future. Users can subscribe to the refreshable, registering a callback which is invoked whenever the value changes. Additionally, users can map a refreshable of one type to a refreshable of another type, with the new refreshable being updated based on changes to the original refreshable. For example, a caching component of a service may map a Refreshable<ServiceConfiguration> down to a Refreshable<CacheConfiguration> so it can subscribe specifically to only the configuration changes that matter to it.

A Subscription is returned when subscribing to a refreshable which acts as a guard type, unregistering the subscription when dropped. If you intend the subscription to last for the lifetime of the refreshable, you can use the Subscription::leak method to allow the Subscription to fall out of scope without unregistering.

A RefreshHandle is returned when creating a new Refreshable which is used to update its value. Subscriptions are fallible, and all errors encountered when running subscriptions in response to an update are reported through the RefreshHandle::refresh method.

Examples

use refreshable::Refreshable;

#[derive(PartialEq)]
struct ServiceConfiguration {
    cache: CacheConfiguration,
    some_other_thing: u32,
}

#[derive(PartialEq, Clone)]
struct CacheConfiguration {
    size: usize,
}

let initial_config = ServiceConfiguration {
    cache: CacheConfiguration {
        size: 10,
    },
    some_other_thing: 5,
};
let (refreshable, mut handle) = Refreshable::new(initial_config);

let cache_refreshable = refreshable.map(|config| config.cache.clone());

let subscription = cache_refreshable.try_subscribe(|cache| {
    if cache.size == 0 {
        Err("cache size must be positive")
    } else {
        println!("new cache size is {}", cache.size);
        Ok(())
    }
}).unwrap();

let new_config = ServiceConfiguration {
    cache: CacheConfiguration {
        size: 20,
    },
    some_other_thing: 5,
};
// "new cache size is 20" is printed.
handle.refresh(new_config).unwrap();

let new_config = ServiceConfiguration {
    cache: CacheConfiguration {
        size: 20,
    },
    some_other_thing: 10,
};
// nothing is printed since the cache configuration did not change.
handle.refresh(new_config).unwrap();

drop(subscription);
let new_config = ServiceConfiguration {
    cache: CacheConfiguration {
        size: 0,
    },
    some_other_thing: 10,
};
// nothing is printed since the the cache subscription was dropped.
handle.refresh(new_config).unwrap();