5 stable releases
2.0.0 | Apr 2, 2024 |
---|---|
1.1.0 | Nov 28, 2022 |
1.0.2 | Mar 17, 2022 |
1.0.1 | Jan 28, 2021 |
1.0.0 | Oct 16, 2020 |
#38 in Caching
6,281 downloads per month
Used in 3 crates
20KB
327 lines
Refreshable
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();
Dependencies
~0.6–5MB
~13K SLoC