Struct Cache 

pub struct Cache<DC>
where
    DC: DataController,
    DC::Key: Send + Sync + 'static,
    DC::Error: Send + Sync + 'static,
{ /* private fields */ }

This is where all the magic happens!

let controller = MyDataController::new(host, port);
let cache = Cache::builder()
    .data_controller(controller)
    .max_updates(1000)
    .max_capacity(100_000)
   .flush_interval(Duration::from_secs(10))
   .build();

// The key type is defined by the data controller implementation of DataController.
cache.entry(key).await?
    .and_try_compute_with(|entry| async {
       let record = if let Some(entry) = entry {
           modify(entry.into_value()).await?
       }
       else {
          create_new().await?
       };

       Ok(Op::Put(record))
    })
    .await?;

Implementations

impl<DC> Cache<DC>

where DC: DataController, DC::Key: Send + Sync + 'static, DC::Error: Send + Sync + 'static,

pub fn error(&self) -> Option<Arc<DC::Error>>

The last error that occurred within the background task. If set, any subsequent call to a public method operating on the cache object will return this error.

pub fn clear_error(&self) -> Option<Arc<DC::Error>>

Clears and returns the last error or None.

pub fn data_controller(&self) -> Arc<DC>

The data controller object.

pub fn max_updates(&self) -> u64

The maximum size of the updates pool. This not a hard limit but a threshold that triggers automatic flushing by the background task.

Defaults to 100.

pub fn max_capacity(&self) -> u64

The maximum cache capacity. This is a hard limit on the number of key entries (not records). See the crate documentation for details.

Defaults to 10000.

pub fn flush_interval(&self) -> Duration

The delay between two consecutive flushes. If a flush was manually requested then the timer is reset.

pub fn set_flush_interval(&mut self, value: Duration) -> Duration

Change the flush interval.

pub fn monitor_tick_duration(&self) -> u64

The period of time between two consecutive checks of the cache state by the background task.

pub fn builder() -> CacheBuilder<DC>

Implement builder pattern for Cache.

impl<DC> Cache<DC>

where DC: DataController,

pub fn name(&self) -> String

Cache name. Most useful for debugging and logging.

pub async fn entry( &self, key: DC::Key, ) -> Result<EntryKeySelector<DC>, Arc<DC::Error>>

Returns an object that represents a key in the cache.

pub async fn get( &self, key: &DC::Key, ) -> Result<Option<DC::Value>, Arc<DC::Error>>

Try to get a value from the cache by its key. If the value is not present, the controller attempts to fetch it via the data controller. Returns None if such a key does not exist.

pub async fn insert( &self, value: DC::Value, ) -> Result<Option<DC::Value>, Arc<DC::Error>>

Insert a value into the cache. This operation triggers the on_new data controller chain of events even in case there is already a value present for the same key.

pub async fn delete( &self, key: &DC::Key, ) -> Result<Option<DC::Value>, Arc<DC::Error>>

Delete a value from the cache by its key. If the value is not cached yet, it will be fetched from the backend first. This behavior is subject to further optimization. In most cases, however, this should not be a problem because if one knows what to delete without inspecting it first or using it in other ways, then it would be more efficient to delete directly in the backend.

pub async fn invalidate(&self, key: &DC::Key) -> Result<(), Arc<DC::Error>>

Invalidate a key in the cache. A secondary key is invalidated by removing it from the cache, while a primary key is invalidated by removing it and all its secondary keys from the cache.

pub async fn flush_many_raw( &self, keys: Vec<DC::Key>, ) -> Result<usize, DC::Error>

Low-level immediate flush operation that requires a list of keys to flush. It does not check for error generated by the background task.

pub async fn flush_raw(&self) -> Result<usize, DC::Error>

The same as the flush method but does not check for error that may have occurred in the background task.

pub async fn flush(&self) -> Result<usize, Arc<DC::Error>>

Immediately flushes all updates in the pool but will do nothing and immediately error out if the background task has encountered an error.

pub async fn soft_flush(&self) -> Result<(), Arc<DC::Error>>

Initiates a flush via the background task.

This method does not wait for the flush to complete; it returns immediately. If the background task has previously encountered an error, this method will do nothing and return that error.

pub async fn flush_one(&self, key: &DC::Key) -> Result<usize, Arc<DC::Error>>

Flushes a single key in the cache. Although the operation itself is inefficient from the caching perspective, it is useful in a multi-cache environment where values in one backend refer to values in another. For example, when there is a foreign key relationship between two tables in a database, a dependent record cannot be written into the backend until its dependency is written first.

This method is most useful when invoked by an observer.

Does nothing and returns an error if the background task has encountered an error.

pub async fn close(&self) -> Result<(), Arc<DC::Error>>

Prepares the cache for shutdown. This method will notify the background task to stop and flush all updates. It will block until the task is finished.

The method is mandatory to be called before the cache is dropped to ensure that no data is lost.

Will do nothing and return an error if the background task has encountered an error.

pub fn is_shut_down(&self) -> bool

Returns the shutdown status of the cache.

Trait Implementations

impl<DC> Debug for Cache<DC>

where DC: DataController,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<DC> Parent for Cache<DC>

where DC: DataController, DC::Key: Send + Sync + 'static, DC::Error: Send + Sync + 'static,

type WeakSelf = Weak<Cache<DC>>

Weak ref-count type for the parent to hold a reference to itself.

fn __fxplus_myself_downgrade(&self) -> Weak<Self>

impl<DC> FXStruct for Cache<DC>

where DC: DataController, DC::Key: Send + Sync + 'static, DC::Error: Send + Sync + 'static,