Skip to content

Commit db84045

Browse files
committed
parser: the marker table indexed, and the phase profile that says where a parse really goes
Item 2 of `docs/parser-review.md` §5.3 said the template path was where a 2× lived. **It is not**, and the value of this commit is half an optimization and half the instrument that disproved the premise. ## What was changed `Marker::complete` asked a `HashMap<usize, bool>` three questions per node, `close_mark` scanned the open stack, and a rollback removed one map entry per position closed since. The positions are event indices on a dense, append-only stream, so the table is now a `Vec<u8>` in lockstep with the events — one byte per event, three states — and: ```text close_mark 4 hash lookups + 2 linear scans per node → three loads, and the LIFO pop is the common case rollback remove an entry per position closed since → truncate the table ``` Measured on 3.98 MB of libstdc++ headers, three runs each side: **2.48–2.52 → 2.54–2.57 MB/s**. Real, reproducible, and 2.5 % — not 2×. It is kept because it is strictly less work per node and a rollback is now a truncation. ## The instrument, and what it says `CPPLS_PARSER_STATS=1` now prints a phase table (inclusive times, `parser/phases.rs`) and a set of counts. On the 3.98 MB unit — 972 104 tokens, 688 159 nodes, 2 467 911 events, 1.59 s: ```text declaration 769 ms 27 306 calls 28.2 µs each specifiers 192 ms 64 052 calls 3.0 µs each ← the largest single named item, 12 % of the parse declarator 82 ms 43 524 calls 1.9 µs each expression 69 ms 49 399 calls 1.4 µs each template-arguments 32 ms 19 114 calls 1.7 µs each tree building 187 ms 688 159 nodes 12 % lexing 27 ms 978 289 tokens 2 % doc layer 10.6 ms 8 887 comment groups 0.7 % counts: 115 086 checkpoints (0.12/token), 15 665 rollbacks, 38 411 type-name questions, 2 751 `>` questions ``` **Per-file cost is flat**: the slowest ten files of the corpus are 113–128 µs/KB against an average of 110. There is no pathological construct in libstdc++, so the 2.5× this corpus costs over plain code is not one hot spot — it is the ordinary price of the constructs headers are made of. That is why the "template path" hypothesis was wrong, and it is now written down with the numbers instead of the guess. The instrument is process-wide behind a mutex rather than thread-local, because `tests/no_global_state.rs` rejected a thread-local — correctly, and it is the second time that test has caught this shape. When the probe is off (the default) the cost is one `OnceLock` load per instrumented call and nothing else: measured 2.57 MB/s off against 2.50 MB/s with the table on. ## Where the next 10 % are `parse_decl_specifier_seq` is 12 % of the parse at 3.0 µs a call over 64 052 calls, and the declaration machinery around it is another ~25 %. Those are named in `docs/parser-review.md` §5.3 as the next targets; **a 2× is not available from any one of them**, which is the finding this commit contributes. `cargo test --workspace`: 79 suites ok; the one failure is the `diagnostics_stable` that was red before this work.
1 parent 3e57e3e commit db84045

10 files changed

Lines changed: 369 additions & 38 deletions

File tree

‎crates/cpp_parser/src/grammar/cpp/decls.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -646,6 +646,7 @@ fn ends_a_template_parameter(p: &CppParser) -> bool {
646646
/// Returns `Err` without having consumed anything when the input does not look like a declaration,
647647
/// so the caller can fall back to parsing an expression statement.
648648
pub fn parse_declaration(p: &mut CppParser) -> ParseResult {
649+
let _phase = crate::parser::phases::during("declaration");
649650
// A declaration is the one place a bare template-id may stand where a *name* belongs, and only when the
650651
// declaration is an **explicit instantiation**: `extern template void f<int>(int);` names the instantiation
651652
// it asks for, and that name is a template-id. Everywhere else `C<T> x;` gives the arguments to the type.

‎crates/cpp_parser/src/grammar/cpp/exprs.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -450,6 +450,7 @@ enum Level {
450450

451451
/// Read an expression down to `level`, optionally reading a trailing `...` as a pack expansion.
452452
fn parse_expr_up_to(p: &mut CppParser, level: Level, pack_expansion: bool) -> ParseResult {
453+
let _phase = crate::parser::phases::during("expression");
453454
let mut expr = parse_ternary_expr(p)?;
454455

455456
if level == Level::Full {

‎crates/cpp_parser/src/grammar/cpp/stats.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -386,6 +386,7 @@ fn block_follow(p: &CppParser) -> bool {
386386
/// node the statement opened, so callers can recover by skipping tokens without having to know how
387387
/// deep the failed rule got.
388388
pub fn parse_stat(p: &mut CppParser) -> ParseResult {
389+
let _phase = crate::parser::phases::during("statement");
389390
let base = p.open_marks();
390391

391392
let result = match p.current_token() {

‎crates/cpp_parser/src/grammar/cpp/types.rs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -788,6 +788,7 @@ fn a_parameter_list_follows_the_attributes(p: &CppParser) -> bool {
788788
}
789789

790790
pub fn parse_decl_specifier_seq(p: &mut CppParser) -> ParseResult {
791+
let _phase = crate::parser::phases::during("specifiers");
791792
parse_decl_specifier_seq_with(p, true, true)
792793
}
793794

@@ -5012,6 +5013,7 @@ fn a_parenthesised_declarator_with_a_name_follows(p: &CppParser) -> bool {
50125013
/// Exposed for the alias rule, which needs it for the same reason the type-id does: `using Arr = int[4];`
50135014
/// writes a type whose array part has nothing enclosing it to attach to.
50145015
pub fn parse_declarator_suffixes(p: &mut CppParser) -> ParseResult {
5016+
let _phase = crate::parser::phases::during("declarator-suffixes");
50155017
loop {
50165018
match p.current_token() {
50175019
CppTokenKind::LeftParen => {
@@ -5056,6 +5058,7 @@ pub fn parse_declarator(p: &mut CppParser) -> ParseResult {
50565058
/// outside a variable declaration's declarator a `[` here is an array bound or a lambda capture, and
50575059
/// reading it as a binding pattern would take those away from the rules that own them.
50585060
pub fn parse_declarator_with(p: &mut CppParser, allow_structured_binding: bool) -> ParseResult {
5061+
let _phase = crate::parser::phases::during("declarator");
50595062
let base = p.open_marks();
50605063
let m = p.mark(CppSyntaxKind::Declarator);
50615064

@@ -5504,6 +5507,7 @@ pub fn parse_template_argument_list(p: &mut CppParser) -> ParseResult {
55045507
}
55055508

55065509
fn parse_template_argument_list_inner(p: &mut CppParser) -> ParseResult {
5510+
let _phase = crate::parser::phases::during("template-arguments");
55075511
let base = p.open_marks();
55085512
let m = p.mark(CppSyntaxKind::TemplateArgumentList);
55095513

‎crates/cpp_parser/src/parser/cpp_parser.rs‎

Lines changed: 151 additions & 33 deletions
Large diffs are not rendered by default.

‎crates/cpp_parser/src/parser/marker.rs‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,9 +41,18 @@ pub(crate) trait MarkerEventContainer {
4141

4242
fn get_events(&mut self) -> &mut Vec<MarkEvent>;
4343

44+
/// **Append one event** — the one way an event enters the stream.
45+
///
46+
/// A container keeps per-position bookkeeping beside the stream (`CppParser::closed_marks` is one byte per
47+
/// event), so a push that bypasses this is a table that drifts one entry out of step with the events. The default
48+
/// is the plain push, for a container with nothing to keep in step.
49+
fn push_event(&mut self, event: MarkEvent) {
50+
self.get_events().push(event);
51+
}
52+
4453
fn mark(&mut self, kind: CppSyntaxKind) -> Marker {
4554
let position = self.get_events().len();
46-
self.get_events().push(MarkEvent::NodeStart {
55+
self.push_event(MarkEvent::NodeStart {
4756
kind,
4857
parent: NO_FORWARD_PARENT,
4958
});
@@ -300,7 +309,7 @@ impl CompleteMarker {
300309
MarkEvent::NodeStart { parent, .. } => *parent = m.position,
301310
_ => unreachable!(),
302311
}
303-
p.get_events().push(MarkEvent::Trivia);
312+
p.push_event(MarkEvent::Trivia);
304313
m
305314
}
306315

‎crates/cpp_parser/src/parser/mod.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
mod cpp_parser;
22
mod marker;
33
mod parser_config;
4+
pub(crate) mod phases;
45
mod type_names;
56

67
pub use cpp_parser::{Checkpoint, CppParser, EventStreamAudit, ParseAnchor};
Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
//! **Where a parse spends its time, by phase** — the instrument that answers "the grammar is 88 % of the parse" with
2+
//! *which part of the grammar*.
3+
//!
4+
//! Off unless `CPPLS_PARSER_STATS=1`, and free when off (one `OnceLock` load per instrumented call). On, every
5+
//! instrumented function takes a timestamp on entry and adds its **inclusive** elapsed time on exit — inclusive, not
6+
//! self, because a phase's children are the interesting part of it, and a tree of inclusive numbers is what says so:
7+
//! `declaration 790 ms`, of which `specifiers 197 ms`, means the declaration machinery around the specifier sequence
8+
//! is 590 ms.
9+
//!
10+
//! # One mutex rather than a thread-local
11+
//!
12+
//! A thread-local would be faster and is what this started as; `tests/no_global_state.rs` rejected it, correctly — the
13+
//! project's rule is that state belongs to an owner, not to a thread. The table is therefore **process-wide** behind a
14+
//! mutex, with the consequence stated rather than discovered: the numbers are only meaningful while one parse is being
15+
//! timed (two parsers on two threads interleave, and the totals are nonsense). Every instrumented call pays one
16+
//! uncontended lock **only when the probe is on**, and nothing at all otherwise.
17+
//!
18+
//! A guard that borrows the parser cannot work — `let _p = p.during(…); parse_x(p)?;` is a double borrow — so the
19+
//! state cannot be a field of it either. Hence the one static.
20+
21+
use std::collections::BTreeMap;
22+
use std::sync::Mutex;
23+
use std::time::Instant;
24+
25+
/// The phase table, allocated on first use and cleared by [`report`].
26+
static STATE: Mutex<Option<State>> = Mutex::new(None);
27+
28+
#[derive(Default)]
29+
struct State {
30+
open: Vec<(&'static str, Instant)>,
31+
/// Inclusive nanoseconds, and how many times the phase ran.
32+
nanos: BTreeMap<&'static str, u64>,
33+
calls: BTreeMap<&'static str, u64>,
34+
}
35+
36+
/// Is the instrument on? Read once; a probe variable set to nothing is off.
37+
fn on() -> bool {
38+
static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
39+
*ON.get_or_init(|| {
40+
std::env::var_os("CPPLS_PARSER_STATS").is_some_and(|value| !value.is_empty())
41+
})
42+
}
43+
44+
/// **Time one run of a phase**, from construction to drop.
45+
///
46+
/// ```ignore
47+
/// let _phase = phases::during("expression");
48+
/// ```
49+
pub struct Phase {
50+
timed: bool,
51+
}
52+
53+
/// Start timing `name` — see [`Phase`].
54+
pub fn during(name: &'static str) -> Phase {
55+
if !on() {
56+
return Phase { timed: false };
57+
}
58+
if let Ok(mut state) = STATE.lock() {
59+
let state = state.get_or_insert_with(State::default);
60+
state.open.push((name, Instant::now()));
61+
}
62+
Phase { timed: true }
63+
}
64+
65+
impl Drop for Phase {
66+
fn drop(&mut self) {
67+
if !self.timed {
68+
return;
69+
}
70+
let Ok(mut state) = STATE.lock() else {
71+
return;
72+
};
73+
let Some(state) = state.as_mut() else {
74+
return;
75+
};
76+
let Some((name, started)) = state.open.pop() else {
77+
return;
78+
};
79+
let took = started.elapsed().as_nanos() as u64;
80+
*state.nanos.entry(name).or_default() += took;
81+
*state.calls.entry(name).or_default() += 1;
82+
}
83+
}
84+
85+
/// **Print what was timed, and forget it** — called once at the end of a parse.
86+
pub fn report() {
87+
if !on() {
88+
return;
89+
}
90+
let Ok(mut state) = STATE.lock() else {
91+
return;
92+
};
93+
let Some(state) = state.as_mut() else {
94+
return;
95+
};
96+
let mut lines: Vec<String> = state
97+
.nanos
98+
.iter()
99+
.map(|(name, nanos)| {
100+
let calls = state.calls.get(name).copied().unwrap_or(0);
101+
format!(
102+
" {name:<20} {:>9.1} ms {:>9} call(s) {:>7.1} µs each",
103+
*nanos as f64 / 1_000_000.0,
104+
calls,
105+
*nanos as f64 / calls.max(1) as f64 / 1000.0,
106+
)
107+
})
108+
.collect();
109+
lines.sort();
110+
eprintln!("parser phases (inclusive):\n{}", lines.join("\n"));
111+
state.nanos.clear();
112+
state.calls.clear();
113+
}

‎crates/cpp_parser/tests/parse_cost.rs‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,20 @@ fn what_parsing_costs() {
126126
));
127127
}
128128
worst.sort_by_key(|(micros, _, _)| std::cmp::Reverse(*micros));
129+
// **The slowest per byte**, which is the table that names a construct: a file is slow because of what it
130+
// contains, and the top of this list is where a grammar spends its time.
131+
let mut dense: Vec<(u128, String)> = worst
132+
.iter()
133+
.map(|(micros, which, bytes)| {
134+
let per_kb = *micros as f64 * 1024.0 / (*bytes as f64).max(1.0);
135+
(per_kb as u128, which.clone())
136+
})
137+
.collect();
138+
dense.sort_by_key(|(per_kb, _)| std::cmp::Reverse(*per_kb));
139+
println!(" slowest per KB:");
140+
for (per_kb, which) in dense.iter().take(10) {
141+
println!(" {per_kb:>6} µs/KB {which}");
142+
}
129143
println!(
130144
"parsed {} file(s), {:.1} MB in {:?} — {:.2} MB/s",
131145
worst.len(),

‎docs/parser-review.md‎

Lines changed: 72 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,35 @@ The important ratio is the last one: **template-dense code costs ~2.5× more per
5353
difference is entirely in the grammar — speculation, `TypeNames` lookups, the `<`-is-it-a-template question. The tree
5454
library's share is stable at 21–24 MB/s whatever the input.
5555

56+
### Where the grammar's time goes
57+
58+
`CPPLS_PARSER_STATS=1` prints a phase table (inclusive times, from `parser/phases.rs`) and a set of counts. On the
59+
3.98 MB standard-header unit — 972 104 tokens, 688 159 nodes, 2 467 911 events — the parse is **1.56 s** and it splits:
60+
61+
```text
62+
declaration 769 ms 27 306 calls 28.2 µs each 48 % of the parse
63+
specifiers 192 ms 64 052 calls 3.0 µs each 12 % ← the largest single named item
64+
declarator 82 ms 43 524 calls 1.9 µs each 5 %
65+
expression 69 ms 49 399 calls 1.4 µs each 4 %
66+
template-arguments 32 ms 19 114 calls 1.7 µs each 2 %
67+
declarator-suffixes 0.1 ms 254 calls
68+
tree building 187 ms 688 159 nodes 12 %
69+
lexing 27 ms 978 289 tokens 2 %
70+
doc layer 10.6 ms 8 887 comment groups 0.7 % (1.2 µs each)
71+
statement 1901 ms 36 804 calls — inflated: a file-scope declaration is parsed *through*
72+
`parse_stat`, and nested statements count for each enclosing one
73+
```
74+
75+
Counts, from the same switch: 115 086 checkpoints (0.12 per token), 15 665 rollbacks, 38 411 type-name questions, 2 751
76+
`>`-closing questions, and the doc layer at ~1 µs per comment group. **Per-file cost is flat** — the slowest ten files
77+
of the corpus are 113–128 µs/KB against an average of 110 — so there is no pathological construct anywhere in
78+
libstdc++, and the 2.5× over plain code is not one hot spot but the ordinary cost of the constructs std headers are
79+
made of.
80+
81+
That last number is the important one for anyone hoping to "optimize the template path": **there is no single place to
82+
win 2×**. The grammar's cost is spread over declaration machinery and per-token work; the best single named target is
83+
`parse_decl_specifier_seq` at 12 % of the parse.
84+
5685
A translation unit is not what a reader feels, either: the analysis parses a **rendering** (the file with its macros
5786
expanded, which for a header-heavy file is the whole closure). The parser's own dump tool records that case: *"on the
5887
3.3 MB cooked `<vector>` stream the parse is about 0.8 s"* — 4 MB/s on the worst realistic input, and close to the
@@ -266,9 +295,10 @@ Ranked by (measured win) ÷ (risk):
266295

267296
1. ~~**Cache the `FileView` per (file, content hash, environment)**~~ — **done**, and the numbers are below. The
268297
analysis re-parsed a rendering on *every* `Session::view`, i.e. on every hover and every pull.
269-
2. **The grammar's template path** (88 % of the std-header parse, 2.5× plain code per byte): profile the speculation
270-
sites (`checkpoint`/`rollback` per declaration) and `is_a_known_type_name` before changing anything — this is where
271-
an afternoon of measurement pays, and it is the only place a 2× is available.
298+
2. ~~**The grammar's template path**~~ — **tried, and the hypothesis was wrong.** There is no template-path hot spot:
299+
per-file cost is flat (§2), the phase table puts 50 % in `parse_declaration` and 12 % in its specifier sequence, and
300+
the counts say speculation is 0.12 checkpoints per token. What was measured and changed is in §5.3; the honest
301+
conclusion is that **a 2× needs several 10 % items**, starting with `parse_decl_specifier_seq` (12 %).
272302
3. **Fix the linkage-block losslessness bug** (§4) — small, and it is a correctness bug in a construct every C header
273303
uses.
274304
4. **`unsafe` removal** (§5.1) — zero risk to change, removes a UB hazard.
@@ -302,6 +332,37 @@ Two things had to change for a session to hold a tree at all:
302332
across the server's threads, so the cache holds a `ParsedView` — everything but the root — and
303333
`FileView::from_parsed` rebuilds it per hit, which is one allocation.
304334

335+
### What item 2 became, measured
336+
337+
Item 2 said the template path was where a 2× lived. **It is not**, and finding that out is the result.
338+
339+
What was tried first was the marker bookkeeping, because `Marker::complete` asked a hash map three questions per node
340+
and `close_mark` scanned the open stack:
341+
342+
```text
343+
closed_marks: HashMap<usize, bool> → Vec<u8> indexed by event position
344+
close_mark 4 hash lookups + 2 linear scans per node → 3 loads, one byte each
345+
rollback remove a map entry per position closed since → truncate the table
346+
2.48 → 2.54–2.57 MB/s (3.98 MB of std headers, three runs after the change against a 2.48–2.52 baseline)
347+
```
348+
349+
Real, reproducible, and **2.5 % — not 2×**. It is kept because it is strictly less work per node and makes a rollback a
350+
truncation, but it is not what the review predicted.
351+
352+
Then the phase table (§2) answered where the time actually is, and the answer rules out the premise: **no hot spot**.
353+
The parse is 1.56 s for 3.98 MB, split `declaration 50 % (specifier sequence 12 %, declarator 5 %, expression 5 %,
354+
template arguments 2 %), tree 12 %, lexing 2 %`, and per-file cost is flat at 110 µs/KB with the slowest file at 128.
355+
A speculative parser that re-reads 12 % of its tokens would show up as a file- or construct-shaped spike; there is
356+
none.
357+
358+
What is left behind for the next round:
359+
360+
* `parser/phases.rs` — the phase timer, `CPPLS_PARSER_STATS=1`, free when off (one relaxed `OnceLock` load per
361+
instrumented call) and inclusive by design, so a parent's number contains its children's.
362+
* `ParserCounts` — checkpoints, rollbacks, type questions, `>` questions, comment groups and their time.
363+
* The measurement that matters: **`parse_decl_specifier_seq` is 12 % of the parse at 3.1 µs a call**, and the
364+
declaration machinery around it is another ~25 %. Those are where a 10 % win each is available; a 2× is not.
365+
305366
## 6. How to reproduce every number
306367

307368
```powershell
@@ -311,6 +372,14 @@ cargo test -p cpp_parser --test lossless
311372
cargo test -p cpp_parser --test lossless -- --ignored # the linkage-block reproducer, red
312373
```
313374

375+
And the phase table behind §2:
376+
377+
```powershell
378+
$env:CPPLS_PROJECT_ROOT = "C:\…\mingw64\lib\gcc\x86_64-w64-mingw32\15.1.0\include\c++"
379+
$env:CPPLS_PARSER_STATS = "1"
380+
cargo test --release -p cpp_parser --test parse_cost -- --ignored --nocapture 2>&1 | Select-String "parser"
381+
```
382+
314383
The std-header corpus used for the hard numbers:
315384

316385
```text

0 commit comments

Comments
 (0)