Struct Cache

Source

pub struct Cache<T> { /* private fields */ }

Expand description

A simple caching struct that can be used to locally maintain a synchronized state with an actor.

Create one via Handle::create_cache (initialized with the current actor value), Handle::create_cache_from (custom initial value), or Handle::create_cache_from_default (starts from T::default()).

Implementations§

Source §

impl<T> Cache<T>
where T: Clone + Send + Sync + 'static,

Source

pub fn has_updates(&self) -> bool

Returns true if there are pending updates from the actor that haven’t been received yet.

§Examples

let handle = Handle::new(1);
let cache = handle.create_cache().await;
assert!(!cache.has_updates());

handle.set(2).await;
assert!(cache.has_updates());

Source

pub fn get_newest(&mut self) -> &T

Returns the newest value available, draining any pending updates from the channel. If the channel is closed, returns the last known value without error.

Note: when the cache is initialized with a default value (e.g. via create_cache_from_default), the returned value may differ from the actor’s actual value until a broadcast occurs.

§Examples

let handle = Handle::new(1);
let mut cache = handle.create_cache_from_default();
assert_eq!(cache.get_newest(), &0); // Not initialized, returns default

handle.set(2).await;
handle.set(3).await;
assert_eq!(cache.get_newest(), &3); // Synchronizes with latest value

Source

pub fn get_current(&self) -> &T

Returns the current cached value without synchronizing with the actor.

Note: when the cache is initialized with a default value (e.g. via create_cache_from_default), the returned value may differ from the actor’s actual value until a broadcast occurs.

§Examples

let handle = Handle::new(1);
let cache = handle.create_cache().await;
assert_eq!(cache.get_current(), &1);

handle.set(2).await;
// Still returns the cached value, not the updated actor value
assert_eq!(cache.get_current(), &1);

Source

pub async fn recv_newest(&mut self) -> Result<&T, CacheRecvNewestError>

Receives the newest broadcasted value from the actor, discarding any older messages.

On the first call, returns the current cached value immediately, even if the channel is closed. On subsequent calls, waits until an update is available.

Note: when the cache is initialized with a default value (e.g. via create_cache_from_default), the first call may return the default while the actor holds a different value.

§Errors

Returns CacheRecvNewestError::Closed if the actor is dropped (after the first call).

§Examples

let handle = Handle::new(1);
let mut cache = handle.create_cache().await;

// First call returns the initialized value immediately
assert_eq!(cache.recv_newest().await.unwrap(), &1);

handle.set(2).await;
handle.set(3).await;
// Skips to newest value, discarding older updates
assert_eq!(cache.recv_newest().await.unwrap(), &3);

Source

pub async fn recv(&mut self) -> Result<&T, CacheRecvError>

Receives the next broadcasted value from the actor (FIFO).

On the first call, returns the current cached value immediately, even if the channel is closed. On subsequent calls, waits until an update is available.

Note: when the cache is initialized with a default value (e.g. via create_cache_from_default), the first call may return the default while the actor holds a different value.

§Errors

Returns CacheRecvError::Closed if the actor is dropped, or CacheRecvError::Lagged if the cache fell behind and messages were dropped.

§Examples

let handle = Handle::new(1);
let mut cache = handle.create_cache().await;

// First call returns the initialized value immediately
assert_eq!(cache.recv().await.unwrap(), &1);

handle.set(2).await;
handle.set(3).await;
// Returns oldest update first (FIFO)
assert_eq!(cache.recv().await.unwrap(), &2);

Source

pub fn try_recv_newest(&mut self) -> Result<Option<&T>, CacheRecvNewestError>

Tries to receive the newest broadcasted value from the actor, discarding any older messages. Returns immediately without waiting.

On the first call, returns Some with the current cached value, even if no updates are present. On subsequent calls, returns None if no new updates are available.

Note: when the cache is initialized with a default value (e.g. via create_cache_from_default), the first call may return the default while the actor holds a different value.

§Errors

Returns CacheRecvNewestError::Closed if the actor is dropped.

§Examples

let handle = Handle::new(1);
let mut cache = handle.create_cache().await;

// First call returns the initialized value
assert_eq!(cache.try_recv_newest().unwrap(), Some(&1));
// No new updates available
assert_eq!(cache.try_recv_newest().unwrap(), None);

handle.set(2).await;
handle.set(3).await;
// Skips to newest value
assert_eq!(cache.try_recv_newest().unwrap(), Some(&3));

When the cache is created from a default value, the actor’s actual value is never received unless a broadcast occurs:

let handle = Handle::new(5);
let mut cache = handle.create_cache_from_default();

// Returns the default, not the actor's actual value (5)
assert_eq!(cache.try_recv_newest().unwrap(), Some(&0));
// No broadcasts arrived, so None — the actor's value (5) is never seen
assert_eq!(cache.try_recv_newest().unwrap(), None);

Source

pub fn try_recv(&mut self) -> Result<Option<&T>, CacheRecvError>

Tries to receive the next broadcasted value from the actor (FIFO). Returns immediately without waiting.

On the first call, returns Some with the current cached value, even if no updates are present or the channel is closed. On subsequent calls, returns None if no new updates are available.

Note: when the cache is initialized with a default value (e.g. via create_cache_from_default), the first call may return the default while the actor holds a different value.

§Errors

Returns CacheRecvError::Closed if the actor is dropped, or CacheRecvError::Lagged if the cache fell behind and messages were dropped.

§Examples

let handle = Handle::new(1);
let mut cache = handle.create_cache().await;

// First call returns the initialized value
assert_eq!(cache.try_recv().unwrap(), Some(&1));
// No new updates available
assert_eq!(cache.try_recv().unwrap(), None);

handle.set(2).await;
handle.set(3).await;
// Returns oldest update first (FIFO)
assert_eq!(cache.try_recv().unwrap(), Some(&2));

When the cache is created from a default value, the actor’s actual value is never received unless a broadcast occurs:

let handle = Handle::new(5);
let mut cache = handle.create_cache_from_default();

// Returns the default, not the actor's actual value (5)
assert_eq!(cache.try_recv().unwrap(), Some(&0));
// No broadcasts arrived, so None — the actor's value (5) is never seen
assert_eq!(cache.try_recv().unwrap(), None);

Source

pub fn blocking_recv(&mut self) -> Result<&T, CacheRecvError>

Blocking version of recv. Receives the next broadcasted value (FIFO). Must not be called from an async context.

On the first call, returns the current cached value immediately, even if the channel is closed. On subsequent calls, blocks until an update is available.

Note: when the cache is initialized with a default value (e.g. via create_cache_from_default), the first call may return the default while the actor holds a different value.

§Errors

Returns CacheRecvError::Closed if the actor is dropped, or CacheRecvError::Lagged if the cache fell behind and messages were dropped.

§Examples

let handle = Handle::new(1);
let mut cache = handle.create_cache().await;
handle.set(2).await;

std::thread::spawn(move || {
    // First call returns the initialized value immediately
    assert_eq!(cache.blocking_recv().unwrap(), &1);
    // Subsequent call receives the update
    assert_eq!(cache.blocking_recv().unwrap(), &2);
}).join().unwrap();

Source

pub fn blocking_recv_newest(&mut self) -> Result<&T, CacheRecvNewestError>

Blocking version of recv_newest. Receives the newest broadcasted value, discarding any older messages. Must not be called from an async context.

On the first call, returns the newest available value immediately, even if the channel is closed. On subsequent calls, blocks until an update is available.

Note: when the cache is initialized with a default value (e.g. via create_cache_from_default), the first call may return the default while the actor holds a different value.

§Errors

Returns CacheRecvNewestError::Closed if the actor is dropped (after the first call).

§Examples

let handle = Handle::new(1);
let mut cache = handle.create_cache().await;
handle.set(2).await;
handle.set(3).await;

std::thread::spawn(move || {
    // First call skips to the newest available value
    assert_eq!(cache.blocking_recv_newest().unwrap(), &3);
}).join().unwrap();

Source

pub fn spawn_throttle<C, F>(&self, client: C, call: fn(&C, F), freq: Frequency)
where C: Send + Sync + 'static, T: Throttled<F>, F: Clone + Send + Sync + 'static,

Spawns a Throttle that fires given a specified Frequency, given any broadcasted updates by the actor. Does not first update the cache to the newest value, since then the user of the cache might miss the update. See Handle::spawn_throttle for an example.