#value #update #cache #refresh #subscription #user #original

refreshable

A simple wrapper around a value that changes over time

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

#41 in Caching

Download history 2275/week @ 2024-07-25 2246/week @ 2024-08-01 2484/week @ 2024-08-08 2008/week @ 2024-08-15 1737/week @ 2024-08-22 1704/week @ 2024-08-29 1641/week @ 2024-09-05 1875/week @ 2024-09-12 1771/week @ 2024-09-19 1616/week @ 2024-09-26 1513/week @ 2024-10-03 294/week @ 2024-10-10 32/week @ 2024-10-17 14/week @ 2024-10-24 22/week @ 2024-10-31 33/week @ 2024-11-07

115 downloads per month
Used in 3 crates

Apache-2.0

20KB
327 lines

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();

Dependencies

~0.5–6MB
~13K SLoC