[−][src]Crate refreshable
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.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();
Structs
Guard | A guard type providing access to a snapshot of a refreshable's current value. |
RefreshHandle | A handle that can update the value associated with a refreshable. |
Refreshable | A wrapper around a live-refreshable value. |
Subscription | A subscription to a |