Method put

salt/utils/mmap_cache.py:1247–1353

Store *key* -> *value* in the cache. *value* may be ``None`` (set/presence mode), a ``str``, or ``bytes``. Returns ``True`` on success, ``False`` on failure. If the key already exists and the new value fits in the existing heap region, the heap bytes are ov

(self, key, value=None)

    # ------------------------------------------------------------------

    def put(self, key, value=None):
        """
        Store *key* -> *value* in the cache.

        *value* may be ``None`` (set/presence mode), a ``str``, or ``bytes``.
        Returns ``True`` on success, ``False`` on failure.

        If the key already exists and the new value fits in the existing heap
        region, the heap bytes are overwritten in-place.  Otherwise the new
        value is appended to the heap and the index pointer is updated.

        Thread-safe: acquires ``_thread_lock`` (RLock) then the cross-process
        ``fcntl.flock`` **before** ``open(write=True)`` maps the index.  Mapping
        prior to the flock would let another writer mutate the file while this
        process holds a stale mmap (multiprocess data loss).
        """
        key_bytes = salt.utils.stringutils.to_bytes(key)[: self.key_size]
        if value is None:
            val_bytes = b""
        elif isinstance(value, bytes):
            val_bytes = value
        else:
            val_bytes = salt.utils.stringutils.to_bytes(value)

        mtime_ns = time.time_ns()

        try:
            with self._thread_lock:
                with self._lock():
                    if not self.open(write=True):
                        return False
                    slot, found = self._find_slot(key_bytes)
                    if slot is None:
                        log.error("Mmap cache index is full!")
                        return False

                    s_offset = slot * self.slot_size

                    if found:
                        existing_heap_off, existing_len, _ = self._read_slot_pointer(
                            s_offset
                        )
                        if len(val_bytes) <= existing_len:
                            # In-place overwrite: hand the actual value
                            # bytes to ``_overwrite_in_heap`` (no NUL
                            # padding).  The slot's LENGTH field becomes
                            # authoritative for reads; trailing bytes
                            # from the previous, larger value remain in
                            # the heap as unreferenced garbage that
                            # ``atomic_rebuild`` reclaims.  Padding here
                            # plus a rstrip CRC inside _overwrite_in_heap
                            # corrupted binary values whose final byte
                            # was NUL — see BUG.md.
                            if not self._overwrite_in_heap(
                                existing_heap_off, val_bytes
                            ):
                                return False
                            struct.pack_into(