Struct EntityCache 

pub struct EntityCache { /* private fields */ }

Entity cache that maintains full projected entities with LRU eviction.

The cache is populated as mutations flow through the projector, regardless of subscriber state. When a new subscriber connects, they receive snapshots of all cached entities for their requested view.

Only whole entities

Source mutations carry only the fields that changed. A patch for a key a view holds merges into the whole entity. A patch for a key it does not hold is stored only if it is the whole entity: storing a few changed fields would serve them as though they were the entity, in snapshots and in every derived view.

A VM linked through crate::EntityResync marks the mutation that creates each entity (PatchOrigin::Creation), which is stored as-is. Any other patch from it for a key a view does not hold (PatchOrigin::Change) is refused with CacheWrite::Refused — whether the view evicted the key or never held it, as after a restore. The projector then asks the VM for the whole entity, which follows in the VM’s next batch and is stored with EntityCache::store_whole. That holds however many entities the VM keeps and however long ago the view evicted the key.

A source that marks nothing (PatchOrigin::Unknown) leaves a new key and an evicted one looking alike. Each view therefore remembers the keys it evicted (bounded, most recent first) and refuses patches for them; a key evicted so long ago that it has been forgotten is taken for new. A source delete also ends an eviction.

Implementations

impl EntityCache

pub fn new() -> Self

Create a new entity cache with default configuration

pub fn with_config(config: EntityCacheConfig) -> Self

Create a new entity cache with custom configuration

pub fn max_entities_per_view(&self) -> usize

Maximum number of entities cached per view.

Derived sorted view caches are bounded by the same value so they never hold more entities than their source view caches.

pub async fn upsert(&self, view_id: &str, key: &str, patch: Value) -> CacheWrite

Write a patch from a source that does not mark creations (PatchOrigin::Unknown).

pub async fn upsert_with_append( &self, view_id: &str, key: &str, patch: Value, append_paths: &[String], origin: PatchOrigin, ) -> CacheWrite

Merge patch into the cached entity, store it as a new entity, or refuse it as part of an entity the cache does not hold (see the type docs).

pub async fn store_whole(&self, view_id: &str, key: &str, entity: Value)

Store entity as the whole entity for key, replacing anything held and clearing an eviction: the source vouched for it being complete (see arete_interpreter::Mutation::mark_whole_entity).

pub fn merge_patch( &self, base: &mut Value, patch: Value, append_paths: &[String], )

Merge a source patch into base with this cache’s append and array rules, for callers that keep their own full copy of an entity.

pub async fn remember_evicted( &self, view_id: &str, keys: impl IntoIterator<Item = String>, )

Treat keys as evicted from view_id unless the view holds them, so patches for them from a source that does not mark creations are refused. Used after a restore, when the VM holds entities the restored cache does not; a VM that marks creations makes this moot, and the view drops the memory with its first patch.

pub async fn get_all(&self, view_id: &str) -> Vec<(String, Value)>

Get all cached entities for a view.

Returns a vector of (key, entity) pairs for sending as snapshots to new subscribers.

pub async fn get_after( &self, view_id: &str, cursor: &str, limit: Option<usize>, ) -> Vec<(String, Value)>

Get entities with _seq greater than the provided cursor.

Returns entities that have been updated after the given cursor, sorted by _seq in ascending order. Useful for resuming from a specific point in the stream.

pub async fn get(&self, view_id: &str, key: &str) -> Option<Value>

Get a specific entity from the cache

pub async fn remove(&self, view_id: &str, key: &str) -> Option<Value>

Remove one entity after a source-wide delete.

The delete ends the entity, so the key is also forgotten as evicted: a later patch for it creates a new entity.

pub async fn len(&self, view_id: &str) -> usize

Get the number of cached entities for a view

pub async fn is_empty(&self, view_id: &str) -> bool

Check if the cache for a view is empty

pub fn snapshot_config(&self) -> SnapshotBatchConfig

Get the snapshot batch configuration

pub async fn clear(&self, view_id: &str)

Clear all cached entities for a view

pub async fn clear_all(&self)

pub async fn dump(&self) -> Vec<(String, Vec<(String, Value)>)>

Dump every view’s entities for a state snapshot.

Entries are ordered most-recently-used first; Self::hydrate relies on that to reconstruct LRU eviction order.

pub async fn hydrate(&self, views: Vec<(String, Vec<(String, Value)>)>)

Restore entities dumped by Self::dump, preserving LRU order.

Entities are inserted as-is (no merge): a snapshot holds fully projected entities, not patches.

pub async fn stats(&self) -> CacheStats

Trait Implementations

impl Clone for EntityCache

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for EntityCache

fn default() -> Self

Returns the “default value” for a type.