~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.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
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.pyindex 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 itemsself._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 cachetry:@@ -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_lockwith self._fetch_locks_lock:# Double-check after acquiring lockresults = self.get(query, search_engine)@@ -353,6 +368,9 @@ class SearchCache:event = threading.Event()self._fetch_events[query_hash] = eventself._fetch_locks[query_hash] = threading.Lock()+ # Capture references while still holding _fetch_locks_lock+ fetch_lock = self._fetch_locks[query_hash]+ fetch_event = eventevent = None # Signal we should fetchelse:# Another thread is actively fetching@@ -362,22 +380,35 @@ class SearchCache:event = threading.Event()self._fetch_events[query_hash] = eventself._fetch_locks[query_hash] = threading.Lock()+ # Capture references while still holding _fetch_locks_lock+ fetch_lock = self._fetch_locks[query_hash]+ fetch_event = eventevent = None # Signal we should fetch# If another thread is fetching, wait for itif 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 Nonewith 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] = resultsreturn 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] = Nonereturn Nonefinally:@@ -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 databasewith 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}%"