Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

fix: add thread safety to SearchCache memory cache (#3138)

LearningCircuitd10ce66ddec4
diff --git a/src/local_deep_research/utilities/search_cache.py b/src/local_deep_research/utilities/search_cache.py
index 457d52a84f..79e26963a4 100644
--- a/src/local_deep_research/utilities/search_cache.py
+++ b/src/local_deep_research/utilities/search_cache.py
@@ -61,8 +61,13 @@ class SearchCache:
# In-memory cache for frequently accessed items
self._memory_cache: Dict[str, Dict[str, Any]] = {}
self._access_times: Dict[str, int] = {}
+ self._memory_lock = threading.Lock()
# Stampede protection: events and locks for each query being fetched
+ #
+ # Lock ordering (to avoid deadlocks):
+ # _fetch_locks_lock -> _memory_lock
+ #
self._fetch_events: Dict[
str, threading.Event
] = {} # query_hash -> threading.Event (signals completion)
@@ -148,7 +153,10 @@ class SearchCache:
logger.exception("Failed to cleanup expired cache entries")
def _evict_lru_memory(self):
- """Evict least recently used items from memory cache."""
+ """Evict least recently used items from memory cache.
+
+ Must be called with ``self._memory_lock`` already held.
+ """
if len(self._memory_cache) <= self.max_memory_items:
return
@@ -179,15 +187,18 @@ class SearchCache:
current_time = int(time.time())
# Check memory cache first
- if query_hash in self._memory_cache:
- entry = self._memory_cache[query_hash]
- if entry["expires_at"] > current_time:
- self._access_times[query_hash] = current_time
- logger.debug(f"Cache hit (memory) for query: {query[:50]}...")
- return entry["results"]
- # Expired, remove from memory
- self._memory_cache.pop(query_hash, None)
- self._access_times.pop(query_hash, None)
+ with self._memory_lock:
+ if query_hash in self._memory_cache:
+ entry = self._memory_cache[query_hash]
+ if entry["expires_at"] > current_time:
+ self._access_times[query_hash] = current_time
+ logger.debug(
+ f"Cache hit (memory) for query: {query[:50]}..."
+ )
+ return entry["results"]
+ # Expired, remove from memory
+ self._memory_cache.pop(query_hash, None)
+ self._access_times.pop(query_hash, None)
# Check database cache
try:
@@ -210,12 +221,13 @@ class SearchCache:
session.commit()
# Add to memory cache
- self._memory_cache[query_hash] = {
- "results": results,
- "expires_at": cache_entry.expires_at,
- }
- self._access_times[query_hash] = current_time
- self._evict_lru_memory()
+ with self._memory_lock:
+ self._memory_cache[query_hash] = {
+ "results": results,
+ "expires_at": cache_entry.expires_at,
+ }
+ self._access_times[query_hash] = current_time
+ self._evict_lru_memory()
logger.debug(
f"Cache hit (database) for query: {query[:50]}..."
@@ -288,12 +300,13 @@ class SearchCache:
session.commit()
# Store in memory cache
- self._memory_cache[query_hash] = {
- "results": results,
- "expires_at": expires_at,
- }
- self._access_times[query_hash] = current_time
- self._evict_lru_memory()
+ with self._memory_lock:
+ self._memory_cache[query_hash] = {
+ "results": results,
+ "expires_at": expires_at,
+ }
+ self._access_times[query_hash] = current_time
+ self._evict_lru_memory()
logger.debug(f"Cached results for query: {query[:50]}...")
return True
@@ -332,6 +345,8 @@ class SearchCache:
return results
# Acquire lock for this query to prevent stampede
+ fetch_lock = None # set inside _fetch_locks_lock
+ fetch_event = None # set inside _fetch_locks_lock
with self._fetch_locks_lock:
# Double-check after acquiring lock
results = self.get(query, search_engine)
@@ -353,6 +368,9 @@ class SearchCache:
event = threading.Event()
self._fetch_events[query_hash] = event
self._fetch_locks[query_hash] = threading.Lock()
+ # Capture references while still holding _fetch_locks_lock
+ fetch_lock = self._fetch_locks[query_hash]
+ fetch_event = event
event = None # Signal we should fetch
else:
# Another thread is actively fetching
@@ -362,22 +380,35 @@ class SearchCache:
event = threading.Event()
self._fetch_events[query_hash] = event
self._fetch_locks[query_hash] = threading.Lock()
+ # Capture references while still holding _fetch_locks_lock
+ fetch_lock = self._fetch_locks[query_hash]
+ fetch_event = event
event = None # Signal we should fetch
# If another thread is fetching, wait for it
if event is not None:
event.wait(timeout=30)
- if query_hash in self._fetch_results:
+ with self._fetch_locks_lock:
result = self._fetch_results.get(query_hash)
- if result is not None:
- return result
+ if result is not None:
+ return result
# Re-check cache, and if still miss, return None (fetch failed)
return self.get(query, search_engine)
- # We are the thread that should fetch
- fetch_lock = self._fetch_locks[query_hash]
- fetch_event = self._fetch_events[query_hash]
-
+ # We are the thread that should fetch (fetch_lock/fetch_event were
+ # captured inside _fetch_locks_lock above when event was set to None).
+ # The guard below is a defensive "can't happen" check: whenever event
+ # is None, both references were assigned in that same locked block. If
+ # a future refactor ever breaks the invariant, degrade to a cache miss
+ # instead of raising -- raising would propagate without setting
+ # fetch_event, stranding any waiting threads for the full 30s timeout.
+ if fetch_lock is None or fetch_event is None:
+ logger.error(
+ "fetch_lock/fetch_event not set inside _fetch_locks_lock; "
+ "treating query '{}' as a fetch failure",
+ query[:50],
+ )
+ return None
with fetch_lock:
# Triple-check (another thread might have fetched while we waited for lock)
results = self.get(query, search_engine)
@@ -398,7 +429,8 @@ class SearchCache:
self.put(query, results, search_engine, ttl)
# Store temporarily for other waiting threads
- self._fetch_results[query_hash] = results
+ with self._fetch_locks_lock:
+ self._fetch_results[query_hash] = results
return results
@@ -407,7 +439,8 @@ class SearchCache:
f"Failed to fetch results for query: {query[:50]}"
)
# Store None to indicate fetch failed
- self._fetch_results[query_hash] = None
+ with self._fetch_locks_lock:
+ self._fetch_results[query_hash] = None
return None
finally:
@@ -431,8 +464,9 @@ class SearchCache:
try:
# Remove from memory
- self._memory_cache.pop(query_hash, None)
- self._access_times.pop(query_hash, None)
+ with self._memory_lock:
+ self._memory_cache.pop(query_hash, None)
+ self._access_times.pop(query_hash, None)
# Remove from database
with self.Session() as session:
@@ -453,8 +487,9 @@ class SearchCache:
def clear_all(self) -> bool:
"""Clear all cached results."""
try:
- self._memory_cache.clear()
- self._access_times.clear()
+ with self._memory_lock:
+ self._memory_cache.clear()
+ self._access_times.clear()
with self.Session() as session:
session.query(SearchCacheModel).delete()
@@ -516,10 +551,13 @@ class SearchCache:
)
avg_access = avg_access_result or 0
+ with self._memory_lock:
+ memory_cache_size = len(self._memory_cache)
+
return {
"total_valid_entries": total_entries,
"expired_entries": expired_entries,
- "memory_cache_size": len(self._memory_cache),
+ "memory_cache_size": memory_cache_size,
"average_access_count": round(avg_access, 2),
"cache_hit_potential": (
f"{(total_entries / (total_entries + 1)) * 100:.1f}%"