Struct Cache 

pub struct Cache {
    pub by_id: Arc<DashMap<AccessiblePrimitive, Arc<RwLock<CacheItem>>, FxBuildHasher>>,
    pub connection: Connection,
}

An internal cache used within Odilia.

This contains (mostly) all accessibles in the entire accessibility tree, and they are referenced by their IDs. If you are having issues with incorrect or invalid accessibles trying to be accessed, this is code is probably the issue.

Fields

by_id: Arc<DashMap<AccessiblePrimitive, Arc<RwLock<CacheItem>>, FxBuildHasher>>

connection: Connection

Implementations

impl Cache

pub fn new(conn: Connection) -> Self

create a new, fresh cache

pub fn add(&self, cache_item: CacheItem) -> OdiliaResult<()>

add a single new item to the cache. Note that this will empty the bucket before inserting the CacheItem into the cache (this is so there is never two items with the same ID stored in the cache at the same time).

Errors

Fails if the internal call to Self::add_ref fails.

pub fn add_ref( &self, id: AccessiblePrimitive, cache_item: &Arc<RwLock<CacheItem>>, ) -> OdiliaResult<()>

Add an item via a reference instead of creating the reference.

Errors

Can error if Cache::populate_references errors. The insertion is guarenteed to succeed.

pub fn remove(&self, id: &AccessiblePrimitive)

Remove a single cache item. This function can not fail.

pub fn get_ref( &self, id: &AccessiblePrimitive, ) -> Option<Arc<RwLock<CacheItem>>>

Get a single item from the cache, this only gets a reference to an item, not the item itself. You will need to either get a read or a write lock on any item returned from this function. It also may return None if a value is not matched to the key.

pub fn get(&self, id: &AccessiblePrimitive) -> Option<CacheItem>

Get a single item from the cache.

This will allow you to get the item without holding any locks to it, at the cost of (1) a clone and (2) no guarantees that the data is kept up-to-date.

pub fn get_all(&self, ids: &[AccessiblePrimitive]) -> Vec<Option<CacheItem>>

get a many items from the cache; this only creates one read handle (note that this will copy all data you would like to access)

pub fn add_all(&self, cache_items: Vec<CacheItem>) -> OdiliaResult<()>

Bulk add many items to the cache; only one accessible should ever be associated with an id.

Errors

An Err(_) variant may be returned if the Cache::populate_references function fails.

pub fn remove_all(&self, ids: &Vec<AccessiblePrimitive>)

Bulk remove all ids in the cache; this only refreshes the cache after removing all items.

pub fn modify_item<F>( &self, id: &AccessiblePrimitive, modify: F, ) -> OdiliaResult<bool>

where F: FnOnce(&mut CacheItem),

Edit a mutable CacheItem. Returns true if the update was successful.

Note: an exclusive lock for the given cache item will be placed for the entire length of the passed function, so try to avoid any compute in it.

Errors

An odilia_common::errors::OdiliaError::PoisoningError may be returned if a write lock can not be aquired on the CacheItem being modified.

pub async fn get_or_create( &self, accessible: &AccessibleProxy<'_>, cache: Weak<Self>, ) -> OdiliaResult<CacheItem>

Get a single item from the cache (note that this copies some integers to a new struct). If the CacheItem is not found, create one, add it to the cache, and return it.

Errors

The function will return an error if:

1. The accessible can not be turned into an AccessiblePrimitive. This should never happen, but is technically possible.
2. The Self::add function fails.
3. The accessible_to_cache_item function fails.

pub fn populate_references( cache: &Arc<DashMap<AccessiblePrimitive, Arc<RwLock<CacheItem>>, FxBuildHasher>>, item_ref: &Arc<RwLock<CacheItem>>, ) -> Result<(), OdiliaError>

Populate children and parent references given a cache and an Arc<RwLock<CacheItem>>. This will unlock the RwLock<_>, update the references for children and parents, then go to the parent and children and do the same: update the parent for the children, then update the children referneces for the parent.

Errors

If any references, either the ones passed in through the item_ref parameter, any children references, or the parent reference are unable to be unlocked, an Err(_) variant will be returned. Technically it can also fail if the index of the item_ref in its parent exceeds usize on the given platform, but this is highly improbable.

Trait Implementations

impl Clone for Cache

fn clone(&self) -> Cache

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Cache

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

Formats the value using the given formatter.