php_lsp/backend/debug_gate.rs
1//! Test-only hold points for blocking-pool work.
2//!
3//! The responsiveness regression tests need to prove a notification handler's
4//! synchronous work runs off the connection's serve future. Requests can pin
5//! that with a pure ordering check (see `assert_stays_responsive` in the test
6//! harness), but a notification has no response to order against — earlier
7//! versions fell back to wall-clock budgets, which flaked on loaded CI
8//! runners. A gate makes the check deterministic instead: the test arms a
9//! named section, the handler's blocking closure parks in `pass` until
10//! released, and the test asserts the server still answers a probe while the
11//! work is provably in flight. On a correct build that holds under any
12//! scheduling; on a regressed (inline) build the serve future itself parks,
13//! no later message is processed, and the probe times out — a hard failure,
14//! never a flake.
15//!
16//! Production builds compile the whole mechanism out: without the
17//! `test-hooks` feature (enabled only for test targets, via the self
18//! dev-dependency in Cargo.toml) `DebugGate` is a zero-sized no-op and the
19//! hold/release custom methods are never registered, so a real client cannot
20//! arm anything.
21
22/// Gate section around `did_open`'s parse-diagnostics closure.
23pub const GATE_DID_OPEN_PARSE: &str = "didOpen.parse";
24/// Gate section around `did_save`'s diagnostics-recompute closure.
25pub const GATE_DID_SAVE_DIAGNOSTICS: &str = "didSave.diagnostics";
26/// Gate section around `did_change_watched_files`' batched parse closure.
27pub const GATE_DID_CHANGE_WATCHED_FILES: &str = "didChangeWatchedFiles.parse";
28/// Gate section around `will_rename_files`' `use`-edit batch closure.
29pub const GATE_WILL_RENAME_FILES: &str = "willRenameFiles.useEdits";
30/// Gate section around `will_delete_files`' `use`-edit batch closure.
31pub const GATE_WILL_DELETE_FILES: &str = "willDeleteFiles.useEdits";
32/// Gate section around `prepare_call_hierarchy`'s indexed-lookup closure.
33pub const GATE_PREPARE_CALL_HIERARCHY: &str = "prepareCallHierarchy.lookup";
34/// Gate section around `selection_range`'s AST-walk closure.
35pub const GATE_SELECTION_RANGE: &str = "selectionRange.walk";
36/// Gate section around `goto_implementation`'s method-decl cursor check.
37pub const GATE_GOTO_IMPLEMENTATION: &str = "gotoImplementation.methodDeclCheck";
38/// Gate section around `goto_definition`'s same-document/index fallback work.
39pub const GATE_GOTO_DEFINITION: &str = "gotoDefinition.lookup";
40/// Gate section around `rename`'s property-decl cursor check + variable rename.
41pub const GATE_RENAME_VARIABLE: &str = "rename.variable";
42/// Gate section around `references`' same-document variable walk.
43pub const GATE_REFERENCES_VARIABLE: &str = "references.variable";
44/// Gate section around `completion_resolve`'s all-indexes signature/doc lookup.
45pub const GATE_COMPLETION_RESOLVE: &str = "completionResolve.lookup";
46/// Gate section around `inlay_hint_resolve`'s all-indexes doc lookup.
47pub const GATE_INLAY_HINT_RESOLVE: &str = "inlayHintResolve.lookup";
48/// Gate section around `on_type_formatting`'s whole-document scan.
49pub const GATE_ON_TYPE_FORMATTING: &str = "onTypeFormatting.scan";
50/// Gate section around `prepare_rename`'s keyword member-access check.
51pub const GATE_PREPARE_RENAME: &str = "prepareRename.walk";
52/// Gate section around `document_symbol`'s AST walk.
53pub const GATE_DOCUMENT_SYMBOL: &str = "documentSymbol.walk";
54/// Gate section around `folding_range`'s AST walk plus comment/region scan.
55pub const GATE_FOLDING_RANGE: &str = "foldingRange.walk";
56/// Gate section around `document_link`'s AST walk plus `@link`/`@see` scan.
57pub const GATE_DOCUMENT_LINK: &str = "documentLink.walk";
58/// Gate section around `semantic_tokens_full`'s AST walk.
59pub const GATE_SEMANTIC_TOKENS_FULL: &str = "semanticTokensFull.walk";
60/// Gate section around `semantic_tokens_range`'s AST walk.
61pub const GATE_SEMANTIC_TOKENS_RANGE: &str = "semanticTokensRange.walk";
62/// Gate section around `semantic_tokens_full_delta`'s AST walk.
63pub const GATE_SEMANTIC_TOKENS_FULL_DELTA: &str = "semanticTokensFullDelta.walk";
64/// Gate section around `linked_editing_range`'s highlight/class-scoping walk.
65pub const GATE_LINKED_EDITING_RANGE: &str = "linkedEditingRange.walk";
66/// Gate section around `goto_type_definition`'s exact-resolution chain.
67pub const GATE_GOTO_TYPE_DEFINITION: &str = "gotoTypeDefinition.walk";
68/// Gate section around type-hierarchy lookup/result construction.
69pub const GATE_TYPE_HIERARCHY: &str = "typeHierarchy.lookup";
70/// Gate section around `moniker`'s AST member lookup.
71pub const GATE_MONIKER: &str = "moniker.lookup";
72/// Gate section around `inline_value`'s range text scan.
73pub const GATE_INLINE_VALUE: &str = "inlineValue.scan";
74/// Gate section around `codeAction/resolve`'s deferred action generation.
75pub const GATE_CODE_ACTION_RESOLVE: &str = "codeActionResolve.generate";
76/// Gate section around the usage-symbol settle-wait in `handle_references`/
77/// `indexed_rename`, held right after mir's own per-file resolution first
78/// comes back empty (companion file not yet known) and before the
79/// wait-then-retry — lets a test force a companion declaring file to open
80/// while mir's resolution attempt is still in flight, so the retry can
81/// observe mir resolving it correctly instead of falling through to the
82/// AST-heuristic FQN fallback.
83pub const GATE_USAGE_SYMBOL_RETRY: &str = "usageSymbol.retry";
84
85#[cfg(not(feature = "test-hooks"))]
86#[derive(Default)]
87pub struct DebugGate;
88
89#[cfg(not(feature = "test-hooks"))]
90impl DebugGate {
91 #[inline(always)]
92 pub fn new() -> Self {
93 DebugGate
94 }
95
96 #[inline(always)]
97 pub fn pass(&self, _section: &str) {}
98
99 #[inline(always)]
100 pub fn held_section(&self) -> Option<String> {
101 None
102 }
103}
104
105#[cfg(feature = "test-hooks")]
106pub use real::DebugGate;
107
108#[cfg(feature = "test-hooks")]
109mod real {
110 use std::sync::{Condvar, Mutex};
111
112 #[derive(Default)]
113 struct GateState {
114 /// Section name the next matching `pass` call should hold at.
115 armed: Option<String>,
116 /// Section currently parked at the gate (surfaced via `debugStats`).
117 held: Option<String>,
118 released: bool,
119 }
120
121 #[derive(Default)]
122 pub struct DebugGate {
123 state: Mutex<GateState>,
124 cv: Condvar,
125 }
126
127 impl DebugGate {
128 pub fn new() -> Self {
129 Self::default()
130 }
131
132 /// Arm the gate: the next `pass(section)` parks until [`release`](Self::release).
133 /// One passage per arm; re-arming replaces any previous armed section.
134 pub fn arm(&self, section: &str) {
135 let mut s = self.state.lock().unwrap();
136 s.armed = Some(section.to_owned());
137 s.released = false;
138 }
139
140 pub fn release(&self) {
141 let mut s = self.state.lock().unwrap();
142 s.armed = None;
143 s.released = true;
144 self.cv.notify_all();
145 }
146
147 /// Section currently parked at the gate, if any.
148 pub fn held_section(&self) -> Option<String> {
149 self.state.lock().unwrap().held.clone()
150 }
151
152 /// Hold point. No-op unless the gate is armed for exactly `section`;
153 /// when it is, claims the arm (so concurrent passages can't stack) and
154 /// parks until released. The park is capped at 60s: a test that fails
155 /// without releasing must not leave this task parked forever — tokio's
156 /// runtime shutdown joins in-flight blocking tasks, so an uncapped park
157 /// would turn that test's failure report into an eternal hang.
158 pub fn pass(&self, section: &str) {
159 let s = self.state.lock().unwrap();
160 if s.armed.as_deref() != Some(section) {
161 return;
162 }
163 let mut s = s;
164 s.armed = None;
165 s.held = Some(section.to_owned());
166 let (mut s, _timed_out) = self
167 .cv
168 .wait_timeout_while(s, std::time::Duration::from_secs(60), |s| !s.released)
169 .unwrap();
170 s.held = None;
171 s.released = false;
172 }
173 }
174}
175
176#[cfg(all(test, feature = "test-hooks"))]
177mod tests {
178 use super::*;
179 use std::sync::Arc;
180
181 #[test]
182 fn unarmed_pass_is_a_no_op() {
183 let gate = DebugGate::default();
184 gate.pass("anything");
185 assert_eq!(gate.held_section(), None);
186 }
187
188 #[test]
189 fn armed_pass_parks_until_release() {
190 let gate = Arc::new(DebugGate::default());
191 gate.arm("sec");
192 let g = Arc::clone(&gate);
193 let t = std::thread::spawn(move || g.pass("sec"));
194 while gate.held_section().as_deref() != Some("sec") {
195 std::thread::yield_now();
196 }
197 assert!(!t.is_finished());
198 gate.release();
199 t.join().unwrap();
200 assert_eq!(gate.held_section(), None);
201 }
202
203 #[test]
204 fn arm_holds_only_the_named_section_and_only_once() {
205 let gate = Arc::new(DebugGate::default());
206 gate.arm("sec");
207 gate.pass("other"); // wrong section: must not park
208 let g = Arc::clone(&gate);
209 let t = std::thread::spawn(move || g.pass("sec"));
210 while gate.held_section().is_none() {
211 std::thread::yield_now();
212 }
213 gate.release();
214 t.join().unwrap();
215 gate.pass("sec"); // arm consumed: must not park again
216 }
217}