2 files changed, 18 insertions, 7 deletions

diff --git a/crates/ra_db/src/cancellation.rs b/crates/ra_db/src/cancellation.rs
index 32a268553..439080075 100644
--- a/crates/ra_db/src/cancellation.rs
+++ b/crates/ra_db/src/cancellation.rs
@@ -21,8 +21,6 @@ pub struct Canceled {
     _private: (),
 }
 
-pub type Cancelable<T> = Result<T, Canceled>;
-
 impl Canceled {
     pub(crate) fn new() -> Canceled {
         Canceled { _private: () }
diff --git a/crates/ra_db/src/lib.rs b/crates/ra_db/src/lib.rs
index 0c4dfc8c6..89113e7a6 100644
--- a/crates/ra_db/src/lib.rs
+++ b/crates/ra_db/src/lib.rs
@@ -10,7 +10,7 @@ use std::panic;
 use ra_syntax::{TextUnit, TextRange, SourceFile, TreeArc};
 
 pub use crate::{
-    cancellation::{Canceled, Cancelable},
+    cancellation::Canceled,
     syntax_ptr::LocalSyntaxPtr,
     input::{
         FilesDatabase, FileId, CrateId, SourceRoot, SourceRootId, CrateGraph, Dependency,
@@ -21,10 +21,23 @@ pub use crate::{
 };
 
 pub trait BaseDatabase: salsa::Database + panic::RefUnwindSafe {
-    fn check_canceled(&self) -> Cancelable<()> {
-        self.salsa_runtime()
-            .if_current_revision_is_canceled(Canceled::throw);
-        Ok(())
+    /// Aborts current query if there are pending changes.
+    ///
+    /// rust-analyzer needs to be able to answer semantic questions about the
+    /// code while the code is being modified. A common problem is that a
+    /// long-running query is being calculated when a new change arrives.
+    ///
+    /// We can't just apply the change immediately: this will cause the pending
+    /// query to see inconsistent state (it will observe an absence of
+    /// repeatable read). So what we do is we **cancel** all pending queries
+    /// before applying the change.
+    ///
+    /// We implement cancellation by panicking with a special value and catching
+    /// it on the API boundary. Salsa explicitly supports this use-case.
+    fn check_canceled(&self) {
+        if self.salsa_runtime().is_current_revision_canceled() {
+            Canceled::throw()
+        }
     }
 
     fn catch_canceled<F: FnOnce(&Self) -> T + panic::UnwindSafe, T>(