#cache #subscription #value #guard #subscribe #error #callback

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

#44 in Caching

Download history 101/week @ 2024-01-29 248/week @ 2024-02-05 36/week @ 2024-02-12 37/week @ 2024-02-26 74/week @ 2024-03-04 1604/week @ 2024-03-11 2176/week @ 2024-03-18 2341/week @ 2024-03-25 2120/week @ 2024-04-01 2021/week @ 2024-04-08 1407/week @ 2024-04-15 1372/week @ 2024-04-22 2073/week @ 2024-04-29 1729/week @ 2024-05-06 1423/week @ 2024-05-13

6,785 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.6–6MB
~13K SLoC