Make DictionaryCache have better expiry properties

synapse/util/caches/dictionary_cache.py

@@ -165,7 +165,8 @@ def get(
         Args:
             key
             dict_keys: If given a set of keys then return only those keys
-                that exist in the cache.
+                that exist in the cache. If None then returns the full dict
+                if it is in the cache.
 
         Returns:
             DictionaryEntry
@@ -251,7 +252,7 @@ def invalidate(self, key: KT) -> None:
         # We want to drop all information about the dict for the given key, so
         # we use `del_multi` to delete it all in one go.
         #
-        # We ignore the type error here `del_mutli` accepts a truncated key
+        # We ignore the type error here: `del_multi` accepts a truncated key
         # (when the key type is a tuple).
         self.cache.del_multi((key,))  # type: ignore[arg-type]
 
@@ -267,7 +268,10 @@ def update(
         value: Dict[DKT, DV],
         fetched_keys: Optional[Iterable[DKT]] = None,
     ) -> None:
-        """Updates the entry in the cache
+        """Updates the entry in the cache.
+
+        Note: This does *not* invalidate any existing entries for the `key`.
+        When the underlying data is changed `.invalidate(key)` must be called.
 
         Args:
             sequence

synapse/util/caches/treecache.py

@@ -69,7 +69,7 @@ def get(self, key, default=None):
 
         If `key` is only a partial key (i.e. a truncated tuple) then returns a
         `TreeCacheNode`, which can be passed to the `iterate_tree_cache_*`
-        functions to iterate over all values in the cache with keys that start
+        functions to iterate over all entries in the cache with keys that start
         with the given partial key.
         """
 

tests/util/test_dict_cache.py

@@ -99,8 +99,11 @@ def test_invalidation(self):
         key = "some_key"
 
         seq = self.cache.sequence
+        # start by populating a "full dict" entry
         self.cache.update(seq, key, {"a": "b", "c": "d"})
 
+        # add a bunch of individual entries, also keeping the individual
+        # entry for "a" warm.
         for i in range(20):
             self.cache.get(key, ["a"])
             self.cache.update(seq, f"key{i}", {1: 2})