Method put

nodedb/src/engine/kv/hash_table/api.rs:90–170

Insert or update a key-value pair. Returns the old value bytes if overwritten. `surrogate` is the row's stable global identity: - On insert of a new row, it is recorded in the reverse map. - On update of an existing row, the entry's existing surrogate is preserved unless `surrogate` is non-zero AND the existing entry is unbound (`Surrogate::ZERO`), in which case the entry is bound. - `Surrogate::

(
        &mut self,
        key: &[u8],
        value: &[u8],
        expire_at_ms: u64,
        surrogate: Surrogate,
    )

    /// Triggers incremental rehash migration if a rehash is in progress.
    /// Triggers a new rehash if the load factor exceeds the threshold.
    pub fn put(
        &mut self,
        key: &[u8],
        value: &[u8],
        expire_at_ms: u64,
        surrogate: Surrogate,
    ) -> Option<Vec<u8>> {
        // Progress incremental rehash.
        self.rehash_step();

        let h = hash_key(key);

        // Check if key exists in primary — update in place (no key copy needed).
        if let Some(idx) = Self::probe_find_index_static(&self.slots, h, key) {
            // probe_find_index_static guarantees slots[idx] is Some.
            let old_value = {
                let slot = self.slots[idx].as_ref()?;
                let v = extract_value_from(&slot.value, &self.overflow);
                free_value_from(&slot.value, &mut self.overflow);
                v
            };
            let new_kv_value = store_value_in(&mut self.overflow, value, self.inline_threshold);
            if let Some(entry) = self.slots[idx].as_mut() {
                entry.value = new_kv_value;
                entry.expire_at_ms = expire_at_ms;
                // Late-bind a surrogate onto a previously-unbound entry.
                if entry.surrogate == Surrogate::ZERO && surrogate != Surrogate::ZERO {
                    entry.surrogate = surrogate;
                    self.surrogate_to_key.insert(surrogate.0, key.to_vec());
                }
            }
            return Some(old_value);
        }

        // Check rehash source — if found, remove from old and insert into primary.
        if let Some(old_slots) = self.rehash_source.as_mut()
            && let Some(idx) = Self::probe_find_index_static(old_slots, h, key)
        {
            let old_entry = old_slots[idx].take()?;
            let old_value = extract_value_from(&old_entry.value, &self.overflow);
            free_value_from(&old_entry.value, &mut self.overflow);
            let new_kv_value = store_value_in(&mut self.overflow, value, self.inline_threshold);
            let preserved = if old_entry.surrogate != Surrogate::ZERO {
                old_entry.surrogate
            } else {
                surrogate
            };
            if preserved != Surrogate::ZERO {
                self.surrogate_to_key.insert(preserved.0, key.to_vec());
            }
            let new_entry = KvEntry {
                hash: h,
                key: key.to_vec(), // Only copy key when migrating from rehash source.
                value: new_kv_value,
                expire_at_ms,
                surrogate: preserved,
            };
            Self::robin_hood_insert(&mut self.slots, new_entry);