Method put

nodedb/src/engine/sparse/doc_cache.rs:160–229

Insert or update a document in the cache (write-through).

(
        &mut self,
        database_id: u64,
        tenant_id: u64,
        collection: &str,
        document_id: &str,
        value: &[u8],
    )

    /// Insert or update a document in the cache (write-through).
    pub fn put(
        &mut self,
        database_id: u64,
        tenant_id: u64,
        collection: &str,
        document_id: &str,
        value: &[u8],
    ) {
        let key = Self::make_key(database_id, tenant_id, collection, document_id);

        // Ensure the shard exists (default weight = 1).
        self.shards
            .entry(database_id)
            .or_insert_with(|| DatabaseShard::new(1));

        // Update in-place if the key is already present.
        {
            let shard = self.shards.get_mut(&database_id).expect("just inserted");
            if let Some(existing) = shard.entries.get_mut(&key) {
                *existing = value.to_vec();
                return;
            }
        }

        // Evict while the cache is at capacity.  When the inserting shard is
        // above its weighted fair share, continue evicting beyond the single
        // "make room" eviction so that resident-set sizes converge toward the
        // weight ratio under sustained pressure.
        //
        // The extra evictions only fire when `total >= capacity` (i.e., the
        // cache is actually full) so the initial warm-up phase is unaffected.
        //
        // `hint_db_id` is passed to the eviction picker so that when two
        // shards have identical overshoot ratios, the inserting shard is
        // preferred — preventing a cold shard at its proportional share from
        // being displaced in favour of the hot inserting shard.
        if self.total >= self.capacity {
            loop {
                if !self.evict_from_highest_overshoot(database_id) {
                    break;
                }
                // After each eviction re-check whether the inserting shard is
                // still above its weighted fair share.
                let total_weight = self.total_weight();
                let fair_share = self
                    .shards
                    .get(&database_id)
                    .map(|s| {
                        (self.capacity as u64)
                            .saturating_mul(s.weight as u64)
                            .saturating_div(total_weight) as usize
                    })
                    .unwrap_or(0);
                let count = self
                    .shards
                    .get(&database_id)
                    .map(|s| s.entries.len())
                    .unwrap_or(0);