//! A vector store a tool call opens on first use, and one that would not open, remembered for a //! while. //! //! An open waits up to 30 seconds for another open of the same store to finish, and fails when a //! holder stays past that (see `crate::lance`). Without the memory here every later call would //! wait out the same stuck holder again before failing. use std::sync::{Arc, Mutex, OnceLock, PoisonError}; use std::time::{Duration, Instant}; use super::EngineError; use crate::lance::LanceStore; /// How long a failed open answers for the store: calls within this of the failure are told at /// once that it is unavailable, and the first call after it opens the store again. pub(crate) const RETRY_AFTER: Duration = Duration::from_secs(60); /// A lazily opened vector store. #[derive(Default)] pub(crate) struct LanceCell { store: OnceLock>, /// Held by the one open running; the calls behind it wait here. opening: Mutex<()>, /// When the last open failed, and why. failed: Mutex>, } impl LanceCell { /// The store, when an open has succeeded. #[cfg_attr(not(feature = "memory"), allow(dead_code, reason = "read only by the memory store"))] pub(crate) fn get(&self) -> Option<&Arc> { self.store.get() } /// The store, opened by `open` unless it is open already. An open that failed less than /// [`RETRY_AFTER`] ago is not tried again: the call fails at once with its reason. pub(crate) fn get_or_open( &self, open: impl FnOnce() -> Result, String>, ) -> Result, Unavailable> { if let Some(store) = self.store.get() { return Ok(Arc::clone(store)); } if let Some(recent) = self.recent_failure() { return Err(recent); } // Opens run one at a time, and a call queued behind one that fails runs its own next: it // looks again here, so calls that arrived during a failing open fail with it instead of // each waiting out the same holder in turn. Only an open that ran records a failure, so a // refusal does not extend the window. let _opening = self.opening.lock().unwrap_or_else(PoisonError::into_inner); if let Some(store) = self.store.get() { return Ok(Arc::clone(store)); } if let Some(recent) = self.recent_failure() { return Err(recent); } match open() { Ok(store) => Ok(Arc::clone(self.store.get_or_init(|| store))), Err(reason) => { *self.failed.lock().unwrap_or_else(PoisonError::into_inner) = Some((Instant::now(), reason.clone())); Err(Unavailable { reason, retry_in: RETRY_AFTER, }) } } } /// The last open's failure, when it failed less than [`RETRY_AFTER`] ago. fn recent_failure(&self) -> Option { let failed = self.failed.lock().unwrap_or_else(PoisonError::into_inner); let (at, reason) = failed.as_ref()?; let retry_in = RETRY_AFTER.checked_sub(at.elapsed()).filter(|left| !left.is_zero())?; Some(Unavailable { reason: reason.clone(), retry_in, }) } } /// A call went without the store: its open failed, now or less than [`RETRY_AFTER`] ago. #[derive(Debug)] pub(crate) struct Unavailable { /// Why the open failed. reason: String, /// How long until a call opens the store again. retry_in: Duration, } impl Unavailable { /// `tool`'s refusal of the call, naming the cause and when to retry, then `meanwhile`: what /// the caller can do without the store. A refusal, not an internal error: nothing is broken in /// the tool, and the same call succeeds once the store opens. pub(crate) fn refusal(&self, tool: &str, meanwhile: Option<&str>) -> EngineError { let mut message = format!("`{tool}`: {self}."); if let Some(meanwhile) = meanwhile { message.push(' '); message.push_str(meanwhile); } EngineError::unavailable(message) } } impl std::fmt::Display for Unavailable { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { write!( f, "vector store unavailable ({}). An open that fails is retried by the first call after {} s; \ retry in about {} s", self.reason, RETRY_AFTER.as_secs(), self.retry_in.as_secs().max(1) ) } } /// The refusal of a call made on no tool's behalf (a backfill step), named by no tool. impl From for EngineError { fn from(unavailable: Unavailable) -> Self { EngineError::unavailable(unavailable.to_string()) } } #[cfg(test)] mod tests { use std::sync::atomic::{AtomicUsize, Ordering}; use super::*; /// Calls that arrive while an open is waiting out a stuck holder queue behind it. When it /// fails they fail with it: none of them opens again and waits out the holder in turn. #[test] fn calls_queued_behind_a_failing_open_fail_with_it() { let cell = LanceCell::default(); let opens = AtomicUsize::new(0); let hold = Duration::from_millis(300); let started = Instant::now(); let answers: Vec = std::thread::scope(|scope| { let calls: Vec<_> = (0..4) .map(|_| { scope.spawn(|| { cell.get_or_open(|| { opens.fetch_add(1, Ordering::SeqCst); std::thread::sleep(hold); Err("the open lock is held".to_string()) }) .is_err() }) }) .collect(); calls.into_iter().map(|call| call.join().expect("call")).collect() }); assert!(answers.iter().all(|failed| *failed), "every call fails"); assert_eq!(opens.load(Ordering::SeqCst), 1, "one open ran for all the calls"); assert!( started.elapsed() < hold * 4, "no call waited past the one open: {:?}", started.elapsed() ); } /// A call inside the window is refused at once, not opened again: the refusal names the tool, /// the store and the first failure's cause, says when to retry, and ends with what the caller /// can do meanwhile. It is a refusal, not an internal error. #[test] fn a_call_inside_the_window_is_refused_by_name_with_when_to_retry() { let cell = LanceCell::default(); let first = cell.get_or_open(|| Err("the open lock is held".to_string())); assert!(first.is_err()); let refused = cell .get_or_open(|| Err("opened again".to_string())) .err() .expect("refused inside the window"); let error = refused.refusal("code_search", Some("Search with `lane: \"keyword\"` meanwhile.")); let EngineError::Unavailable(message) = error else { panic!("a refusal, not an internal error: {error:?}"); }; assert!( message.starts_with("`code_search`: vector store unavailable (the open lock is held)"), "{message}" ); assert!(message.contains("retry in about "), "{message}"); assert!( message.ends_with("Search with `lane: \"keyword\"` meanwhile."), "{message}" ); } }