Reduce redundant file parsing by deduplicating concurrent parses

Author: AJenbo

docs/CHANGELOG.md

@@ -47,6 +47,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Replace FQCN with import.** Now replaces all occurrences of the same FQCN throughout the file in one action, not just the one under the cursor. A new "Replace all FQCNs with imports" action appears when the file contains multiple distinct FQCNs, replacing all of them at once (skipping those with import conflicts).
 - **LSP responsiveness.** Hover, go-to-definition, signature help, code actions, rename, and other handlers now run on background threads. Slow requests no longer block other requests or cancellations.
 - **Faster analysis.** Analysis time cut significantly on large projects.
+- **Reduced redundant file parsing.** Concurrent threads resolving the same vendor class no longer parse the file in parallel; the second thread waits for the first to finish.
 - **Editing responsiveness.** Classes evicted from the cache after a file edit are now eagerly re-populated in dependency order.
 - **Diagnostic delivery model.** Editors that support pull diagnostics now get diagnostics on first file open without waiting for a debounce timer. Updates from external tools no longer re-run the entire native diagnostic pipeline.
 - **Virtual member resolution.** Mixins and virtual accessors are now resolved completely on every class, eliminating cases where they were missing after edits.

docs/todo/performance.md

@@ -220,27 +220,6 @@ path).
 
 ---
 
-## P10. Redundant `parse_and_cache_file` from multiple threads
-
-**Impact: Medium · Effort: Low**
-
-When two threads simultaneously try to resolve the same vendor
-class, both miss `fqn_index`, both call `parse_and_cache_file`,
-and both parse the same file. The second parse is wasted work.
-This is most visible during the Phase 2 diagnostic pass when many
-threads resolve vendor classes for the first time.
-
-### Fix
-
-Add a `DashSet<String>` (or similar) of "currently being parsed"
-URIs. Before calling `parse_and_cache_file`, insert the URI into
-the set. If the insert fails (another thread is already parsing
-it), spin-wait or skip and let the other thread's result propagate
-through `fqn_index`. Remove the URI from the set after parsing
-completes.
-
----
-
 ## P11. Uncached base-resolution in `build_scope_methods_for_builder`
 
 **Impact: Low-Medium · Effort: Low**

src/lib.rs

@@ -343,6 +343,13 @@ pub struct Backend {
     /// classmap contains a phar-based path (detected by a `!` separator,
     /// e.g. `/path/to/phpstan.phar!src/Type/Type.php`).
     pub(crate) phar_archives: Arc<RwLock<HashMap<PathBuf, phar::PharArchive>>>,
+    /// Set of file URIs currently being parsed by another thread.
+    ///
+    /// Used by [`parse_and_cache_file`](Self::parse_and_cache_file) to avoid
+    /// redundant concurrent parses of the same file.  Before parsing, the URI
+    /// is inserted; if it was already present, the calling thread waits for
+    /// the result to appear in `ast_map` instead of re-parsing.
+    pub(crate) parse_inflight: Arc<Mutex<HashSet<String>>>,
     /// Embedded PHP stubs for built-in classes/interfaces (e.g. `UnitEnum`,
     /// `BackedEnum`, `Iterator`, `Countable`, …).
     /// Maps class short name → raw PHP source code.
@@ -638,6 +645,7 @@ impl Backend {
             class_not_found_cache: Arc::new(RwLock::new(HashSet::new())),
             classmap: Arc::new(RwLock::new(HashMap::new())),
             phar_archives: Arc::new(RwLock::new(HashMap::new())),
+            parse_inflight: Arc::new(Mutex::new(HashSet::new())),
             stub_index: RwLock::new(stubs::build_stub_class_index()),
             stub_function_index: RwLock::new(stubs::build_stub_function_index()),
             stub_constant_index: RwLock::new(stubs::build_stub_constant_index()),
@@ -713,6 +721,7 @@ impl Backend {
             class_not_found_cache: Arc::new(RwLock::new(HashSet::new())),
             classmap: Arc::new(RwLock::new(HashMap::new())),
             phar_archives: Arc::new(RwLock::new(HashMap::new())),
+            parse_inflight: Arc::new(Mutex::new(HashSet::new())),
             stub_index: RwLock::new(HashMap::new()),
             stub_function_index: RwLock::new(HashMap::new()),
             stub_constant_index: RwLock::new(HashMap::new()),
@@ -1009,6 +1018,7 @@ impl Backend {
             fqn_index: Arc::clone(&self.fqn_index),
             classmap: Arc::clone(&self.classmap),
             phar_archives: Arc::clone(&self.phar_archives),
+            parse_inflight: Arc::clone(&self.parse_inflight),
             class_not_found_cache: Arc::clone(&self.class_not_found_cache),
             stub_index: RwLock::new(self.stub_index.read().clone()),
             resolved_class_cache: Arc::clone(&self.resolved_class_cache),

src/resolution.rs

@@ -277,19 +277,49 @@ impl Backend {
             let phar_path = Path::new(&path_str[..sep]);
             let internal_path = &path_str[sep + 1..];
 
-            let archives = self.phar_archives.read();
-            let archive = archives.get(phar_path)?;
-            let bytes = archive.read_file(internal_path)?;
-            let content = std::str::from_utf8(bytes).ok()?;
-
             let uri = format!("phar://{}/{}", phar_path.display(), internal_path);
-            return self.parse_and_cache_content(content, &uri);
+
+            // Deduplicate concurrent parses of the same phar entry.
+            if !self.parse_inflight.lock().insert(uri.clone()) {
+                return self.wait_for_cached_result(&uri);
+            }
+            let result = (|| {
+                let archives = self.phar_archives.read();
+                let archive = archives.get(phar_path)?;
+                let bytes = archive.read_file(internal_path)?;
+                let content = std::str::from_utf8(bytes).ok()?;
+                self.parse_and_cache_content(content, &uri)
+            })();
+            self.parse_inflight.lock().remove(&uri);
+            return result;
         }
 
         // ── Regular file path ───────────────────────────────────
-        let content = std::fs::read_to_string(file_path).ok()?;
         let uri = crate::util::path_to_uri(file_path);
-        self.parse_and_cache_content(&content, &uri)
+
+        // Deduplicate concurrent parses of the same file.
+        if !self.parse_inflight.lock().insert(uri.clone()) {
+            return self.wait_for_cached_result(&uri);
+        }
+        let content = std::fs::read_to_string(file_path).ok();
+        let result = content.and_then(|c| self.parse_and_cache_content(&c, &uri));
+        self.parse_inflight.lock().remove(&uri);
+        result
+    }
+
+    /// Spin-wait for another thread to finish parsing a file and return
+    /// the cached result from `ast_map`.
+    fn wait_for_cached_result(&self, uri: &str) -> Option<Vec<Arc<ClassInfo>>> {
+        for _ in 0..200 {
+            // Check if parsing is complete (URI removed from inflight set).
+            if !self.parse_inflight.lock().contains(uri) {
+                return self.ast_map.read().get(uri).cloned();
+            }
+            std::thread::sleep(std::time::Duration::from_millis(1));
+        }
+        // Timeout: the other thread is still parsing.  Return whatever is
+        // in ast_map (may be stale or None).
+        self.ast_map.read().get(uri).cloned()
     }
 
     /// Parse PHP source text, cache the results in