perf(parsing): dispatch element-content markup on the byte after '<' (#276)

The element-content markup dispatch ran up to five literal string
comparisons (</, <!--, <![CDATA[, <?, <!DOCTYPE) before the start-tag
branch won, a per-element cost the parse profile indicted as
Reader.matchesBytes. Branch instead on the single byte after '<' on the
byte fast path: '/' end tag, '?' processing instruction, '!' a
declaration, otherwise a start tag.

The Character path keeps the equivalent matches()-based dispatch for a
streaming source or spliced entity text, and a '<!' that matches none of
comment/CDATA/DOCTYPE still falls through to the start-tag scanner with
the same expectedName error. Measured parse ~9.5x -> ~9.0x slower than
libxml2 on the 20k-item corpus; the byte and Character paths are held
identical by ParserPathDifferentialTests over its adversarial corpus,
and the Xalan, W3C, and RELAX NG suites stay green. No spec behavior
changed.
This commit is contained in:
Mihaela Mihaljevic 2026-06-24 19:25:10 +02:00 committed by GitHub
parent 2f8ca9b289
commit ead838f83c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 51 additions and 9 deletions

View File

@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Parser throughput on plain-ASCII documents roughly halved against the libxml2 reference (measured `parse` 20.1x -> 9.5x slower than libxml2 on the 20k-item generated corpus, `bash scripts/benchmark.sh 20000 5`; ~53% wall-clock reduction). The work was profile-driven (macOS `sample`, not guesswork): the scanner, not tree construction, dominated parse time (SAX is ~84% of parse), and within it the cost was per-`Character` `String` machinery (`String.Iterator.next`, `_stringCompareWithSmolCheck`, `_uncheckedFromUTF8`, bridge-object ARC). The root cause was that a single buffered lookahead `Character` defeated every existing byte fast path (each requires an empty buffer), and the content/markup/attribute dispatch all peeked a `Character` before scanning. The fix keeps the reader on the byte path: a non-buffering `peekByte` for dispatch, a byte-mode `skipSpace`, an all-ASCII `takeASCIIName`, an `attributeRunBytes` bulk scanner (with the 3.3.3 whitespace-to-space transform, deferring any carriage return to the Character path so CRLF is not double-counted), and a `sawAmpersand` flag so ampersand-free text skips reference decoding entirely. The single highest-leverage change was detecting the closing `<` of a text run via `peekByte` instead of buffering it, which had been cascading the next element's whole dispatch and name scan onto the slow path. The Character path remains the exact fallback for a streaming source, spliced entity text, and any non-ASCII byte; byte and Character paths are kept from diverging by `scanContentMarkup` (shared dispatch) and by `ByteFastPathTests`, which pins the fast-path/fallback boundaries (non-ASCII names, CRLF and character references in attribute values, ampersand-free vs entity-bearing text, over-long names, raw `<` in attributes). Verified against the full local suite (1668 tests) plus the Apache Xalan XSLT gold-output corpus, the W3C XML conformance corpora (xmltest, OASIS, Sun, Eduni, IBM, Japanese), and the RELAX NG spec suite, all green; no spec behavior changed.
- Element-content markup dispatch now branches on the single byte after `<` (end tag, processing instruction, declaration, or start tag) instead of running up to five literal string comparisons per element before the start-tag branch wins, a per-element cost the profile indicted (`Reader.matchesBytes`). The Character path keeps the equivalent `matches()`-based dispatch for a streaming source or spliced entity text, and a `<!` that matches none of comment/CDATA/DOCTYPE still falls through to the start-tag scanner with the same `expectedName` error. Measured `parse` ~9.5x -> ~9.0x slower than libxml2 on the 20k-item corpus; the byte and Character paths are held identical by the differential oracle (`ParserPathDifferentialTests`). No spec behavior changed.
## [0.3.0] - 2026-06-24
### Added

View File

@ -4,25 +4,64 @@ extension PureXML.Parsing.EventReader {
/// At a '<' in element content, dispatches to the matching markup scanner.
/// The caller has confirmed the lead is '<' and set the event start. Shared
/// by the byte and Character dispatch paths so the two cannot diverge.
///
/// On the byte fast path the single byte after '<' selects the branch ('/'
/// end tag, '?' PI, '!' a declaration, otherwise a start tag), so an
/// element no longer runs up to five literal string comparisons before the
/// start-tag branch wins. The Character path below is the exact fallback for
/// a streaming source or spliced entity text, and a '<!' that matches none
/// of comment/CDATA/DOCTYPE still falls through to the start-tag scanner,
/// which reports the same `expectedName` error as before.
mutating func scanContentMarkup() throws -> Event {
switch reader.peekByte(1) {
case 0x2F: // '/'
try scanEndTag()
case 0x3F: // '?'
try scanContentProcessingInstruction()
case 0x21: // '!'
try scanContentDeclaration()
case .some:
try scanStartTag()
case nil:
try scanContentMarkupViaCharacters()
}
}
/// The Character-path markup dispatch, used off the byte fast path (a
/// streaming source or spliced entity text). Equivalent to the byte switch
/// in `scanContentMarkup`.
private mutating func scanContentMarkupViaCharacters() throws -> Event {
if reader.matches("</") { return try scanEndTag() }
if reader.matches("<?") { return try scanContentProcessingInstruction() }
if reader.matches("<!") { return try scanContentDeclaration() }
return try scanStartTag()
}
/// Scans a `<!...` construct in element content: a comment, a CDATA
/// section, or a rejected DOCTYPE. A `<!` matching none of these falls
/// through to the start-tag scanner, which reports the same `expectedName`
/// error as before.
private mutating func scanContentDeclaration() throws -> Event {
if reader.matches("<!--") {
recordEmptyElementContent("a comment")
return try scanComment()
}
if reader.matches("<![CDATA[") { return try scanCDATA() }
if reader.matches("<?") {
let mark = reader.mark
recordEmptyElementContent("a processing instruction")
let instruction = try scanProcessingInstruction()
if instruction.target.lowercased() == "xml" {
throw PureXML.Parsing.ParseError.reservedProcessingInstructionTarget(mark)
}
return .processingInstruction(target: instruction.target, data: instruction.data)
}
if reader.matches("<!DOCTYPE") {
throw PureXML.Parsing.ParseError.unsupportedDoctype(reader.mark)
}
return try scanStartTag()
}
/// Scans a processing instruction in element content, rejecting the
/// reserved `xml` target (legal only as the document's leading declaration).
private mutating func scanContentProcessingInstruction() throws -> Event {
let mark = reader.mark
recordEmptyElementContent("a processing instruction")
let instruction = try scanProcessingInstruction()
if instruction.target.lowercased() == "xml" {
throw PureXML.Parsing.ParseError.reservedProcessingInstructionTarget(mark)
}
return .processingInstruction(target: instruction.target, data: instruction.data)
}
}

View File

@ -57,6 +57,7 @@ offsets throughout; libxml2's xmlReadMemory takes an int byte count).
| 3 | bulk content runs (plain-ASCII character data scanned and consumed at the byte level, String built once per run) | 0.335 s (20x) | unchanged | unchanged |
| 4 | byte-level dispatch + name/attribute scanning (non-buffering `peekByte`, byte-mode `skipSpace`, all-ASCII `takeASCIIName`, `attributeRunBytes`); keeps the lookahead buffer empty so the existing byte fast paths engage | 0.217 s (13x) | unchanged | unchanged |
| 5 | `sawAmpersand` short-circuit (ampersand-free text returns verbatim, skipping the reference-decode/split/findings pass) and detecting the text-run-closing `<` via `peekByte` instead of buffering it (the buffered `<` had cascaded the next element's whole dispatch and name scan onto the Character path) | 0.157 s (9.5x) | unchanged | unchanged |
| 6 | byte-level markup dispatch (the single byte after `<` selects end-tag/PI/declaration/start-tag, replacing up to five literal string comparisons per element with one byte peek) | 0.147 s (9.0x) | unchanged | unchanged |
## Profile findings (first sample, parse path)