perf(xpath): cache the document node list for following/preceding axes (#302)

following(of:) and preceding(of:) rebuilt the entire document node list and ran
a linear firstIndex search for the context node on every call. Evaluated over
many context nodes (//x/following::y), that rebuild-and-search was quadratic: a
200-context following:: query over a 20k-element document took ~16s.

Share a per-evaluation DocumentNavigationCache: each document's ordered node
list and a node-to-index map are built once (the document is immutable during
evaluation) and reused, so the position lookup is O(1). following:: also skips
the context's contiguous subtree by index arithmetic (start = index + 1 +
descendant count) instead of scanning the tail and filtering every descendant
out. The selected nodes and their document order are unchanged.

The 200-context query drops ~16s to ~9s; the residual is the produced
node-set's own size (materialization), which is inherent to the axis. The full
suite, the W3C XPath/XSLT and Apache Xalan corpora, and the WASM build stay
green; FollowingPrecedingAxisTests pins the subtree skip, ancestor exclusion,
and the shared-cache multi-context path.
This commit is contained in:
Mihaela Mihaljevic 2026-06-25 20:03:45 +02:00 committed by GitHub
parent 8abaf570bc
commit ad289b0df1
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 139 additions and 26 deletions

View File

@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Fixed
- The `following` and `preceding` axes no longer rebuild the whole document node list and linearly search it on every context node, which made them quadratic over many context nodes. They now share a per-evaluation cache of each document's ordered node list and a node-to-index map (the document does not change during evaluation), so the list is built once and a node's position is an O(1) lookup; `following` additionally skips the context's contiguous subtree by index arithmetic rather than filtering every descendant out. The selected nodes and their order are unchanged. A 200-context `following::` query over a 20k-element document drops from about 16 s to about 9 s; the residual cost is the size of the produced node-set itself. Guarded by `FollowingPrecedingAxisTests`.
## [0.4.3] - 2026-06-25
### Fixed

View File

@ -5,8 +5,8 @@ extension PureXML.XPath {
enum AxisNavigation {
private static let xmlNamespaceURI = "http://www.w3.org/XML/1998/namespace"
static func nodes(on axis: Axis, from context: Node) -> [Node] {
verticalNodes(on: axis, from: context) ?? lateralNodes(on: axis, from: context)
static func nodes(on axis: Axis, from context: Node, cache: DocumentNavigationCache? = nil) -> [Node] {
verticalNodes(on: axis, from: context) ?? lateralNodes(on: axis, from: context, cache: cache)
}
/// The self, child, descendant, parent, and ancestor families; nil for an
@ -25,12 +25,12 @@ extension PureXML.XPath {
}
/// The sibling, following/preceding, attribute, and namespace axes.
private static func lateralNodes(on axis: Axis, from context: Node) -> [Node] {
private static func lateralNodes(on axis: Axis, from context: Node, cache: DocumentNavigationCache?) -> [Node] {
switch axis {
case .followingSibling: followingSiblings(of: context)
case .precedingSibling: precedingSiblings(of: context)
case .following: following(of: context)
case .preceding: preceding(of: context)
case .following: following(of: context, cache: cache)
case .preceding: preceding(of: context, cache: cache)
case .attribute: attributes(of: context)
case .namespace: namespaces(of: context)
default: []
@ -119,25 +119,70 @@ extension PureXML.XPath {
return parent.children[..<index].reversed().map(Node.tree)
}
private static func following(of node: Node) -> [Node] {
let all = documentNodes(of: node)
if let index = all.firstIndex(of: node) {
let excluded = Set(descendants(of: node))
return all[(index + 1)...].filter { !excluded.contains($0) }
private static func following(of node: Node, cache: DocumentNavigationCache?) -> [Node] {
guard let root = rootTree(of: node) else { return [] }
let document = orderedDocument(rootedAt: root, cache: cache)
if let index = document.index[node] {
// A node's descendants are the contiguous block right after it in
// document order, so the following axis begins just past the
// subtree. Skip it by index rather than scanning the whole tail
// and filtering each descendant out (which made this quadratic).
let start = index + 1 + descendantCount(of: node)
return start < document.nodes.count ? Array(document.nodes[start...]) : []
}
// An attribute or namespace start: document order places it after
// its owner and before the owner's children, and it has no
// descendants, so everything after the owner follows.
guard let owner = node.parent, let index = all.firstIndex(of: owner) else { return [] }
return Array(all[(index + 1)...])
guard let owner = node.parent, let index = document.index[owner] else { return [] }
return Array(document.nodes[(index + 1)...])
}
private static func preceding(of node: Node) -> [Node] {
let all = documentNodes(of: node)
let anchorIndex = all.firstIndex(of: node) ?? node.parent.flatMap { all.firstIndex(of: $0) }
private static func preceding(of node: Node, cache: DocumentNavigationCache?) -> [Node] {
guard let root = rootTree(of: node) else { return [] }
let document = orderedDocument(rootedAt: root, cache: cache)
let anchorIndex = document.index[node] ?? node.parent.flatMap { document.index[$0] }
guard let index = anchorIndex else { return [] }
// The excluded ancestors are few (the depth), so a membership filter
// over the preceding span is fine; the win here is the cached node
// list and the O(1) anchor lookup instead of a rebuild and scan.
let excluded = Set(ancestors(of: node))
return all[..<index].filter { !excluded.contains($0) }.reversed()
return document.nodes[..<index].filter { !excluded.contains($0) }.reversed()
}
/// The number of tree-node descendants of `node`, matching what the
/// document node list counts after it (attribute and namespace nodes are
/// not in that list, so they are not counted).
private static func descendantCount(of node: Node) -> Int {
guard case let .tree(tree) = node else { return 0 }
return subtreeNodeCount(tree) - 1
}
private static func subtreeNodeCount(_ tree: PureXML.Model.TreeNode) -> Int {
var count = 1
for child in tree.children {
count += subtreeNodeCount(child)
}
return count
}
/// The document's nodes in document order plus a node-to-index map, built
/// once per document root and reused across the following and preceding
/// evaluations of one query.
private static func orderedDocument(
rootedAt root: PureXML.Model.TreeNode,
cache: DocumentNavigationCache?,
) -> (nodes: [Node], index: [Node: Int]) {
if let cache, let hit = cache.byRoot[ObjectIdentifier(root)] { return hit }
var nodes: [Node] = []
appendSubtree(root, into: &nodes)
var index: [Node: Int] = [:]
index.reserveCapacity(nodes.count)
for (offset, node) in nodes.enumerated() {
index[node] = offset
}
let entry = (nodes: nodes, index: index)
cache?.byRoot[ObjectIdentifier(root)] = entry
return entry
}
private static func attributes(of node: Node) -> [Node] {
@ -202,15 +247,6 @@ extension PureXML.XPath {
return (parent, index)
}
/// Every tree node of the containing document, in document order. Used to
/// derive the following and preceding axes by position.
private static func documentNodes(of node: Node) -> [Node] {
guard let root = rootTree(of: node) else { return [] }
var result: [Node] = []
appendSubtree(root, into: &result)
return result
}
private static func appendSubtree(_ tree: PureXML.Model.TreeNode, into result: inout [Node]) {
result.append(.tree(tree))
for child in tree.children {
@ -230,4 +266,15 @@ extension PureXML.XPath {
return current
}
}
/// A per-query cache of each document's ordered node list and node-to-index
/// map, for the following and preceding axes. Without it those axes rebuild
/// the whole node list and linearly search it on every context node, which is
/// quadratic over a wide document. The document does not change during an
/// evaluation, so caching by root identity is safe.
final class DocumentNavigationCache {
fileprivate var byRoot: [ObjectIdentifier: (nodes: [Node], index: [Node: Int])] = [:]
init() {}
}
}

View File

@ -18,6 +18,10 @@ extension PureXML.XPath {
let functions: FunctionTable
let namespaces: [String: String]
let budget: Budget?
/// Shared across the whole evaluation: the following and preceding axes
/// cache each document's ordered node list here instead of rebuilding it
/// per context node.
let documentNavigation = DocumentNavigationCache()
init(variables: [String: Value], functions: FunctionTable, namespaces: [String: String], budget: Budget?) {
self.variables = variables

View File

@ -68,7 +68,11 @@ extension PureXML.XPath.Evaluator {
}
}
let keep = compiledNodeTest(step.test, on: step.axis, context.namespaces)
return PureXML.XPath.AxisNavigation.nodes(on: step.axis, from: contextNode).filter(keep)
return PureXML.XPath.AxisNavigation.nodes(
on: step.axis,
from: contextNode,
cache: context.environment.documentNavigation,
).filter(keep)
}
/// Filters nodes through each predicate in turn. A numeric predicate is a

View File

@ -0,0 +1,54 @@
import Testing
@testable import PureXML
/// The following and preceding axes now share a per-query cache of the document
/// node list and a node-to-index map (instead of rebuilding and linearly
/// searching the whole document on every context node), and `following::` skips
/// the context's contiguous subtree by index arithmetic rather than filtering
/// every descendant out. These pin that the selected nodes and their order are
/// unchanged across nesting (where the subtree skip must count every descendant)
/// and multiple context nodes (where the cache is shared).
@Suite("following and preceding axes")
struct FollowingPrecedingAxisTests {
private func names(_ path: String, _ xml: String) throws -> [String] {
try PureXML.XPath.Query(path).evaluate(over: PureXML.parse(xml)).compactMap {
if case let .node(node) = $0 { return node.element?.name.localName }
return nil
}
}
private static let doc = "<r><a><a1/><a2/></a><b><b1><b11/></b1></b><c/><a><a3/></a></r>"
@Test("following:: skips the context's whole subtree, in document order")
func test_following() throws {
// From <b>, following is c and the second <a> and its child a3 (NOT b's
// own descendants b1/b11). The subtree-skip by index must count b1 and
// b11 so it lands past them.
#expect(try names("//b/following::*", Self.doc) == ["c", "a", "a3"])
// From a deeply nested node, following is everything after its subtree.
#expect(try names("//a1/following::*", Self.doc) == ["a2", "b", "b1", "b11", "c", "a", "a3"])
// following of a node with no following nodes is empty.
#expect(try names("//a3/following::*", Self.doc) == [])
}
@Test("preceding:: excludes ancestors")
func test_preceding() throws {
// The path result is a deduplicated node-set returned in document order.
// From <c>, preceding is everything before it except its ancestors (only
// r), so a, a1, a2, b, b1, b11.
#expect(try names("//c/preceding::*", Self.doc) == ["a", "a1", "a2", "b", "b1", "b11"])
// From b11, preceding excludes its ancestors b, b1 (and r), leaving the
// first <a> subtree.
#expect(try names("//b11/preceding::*", Self.doc) == ["a", "a1", "a2"])
}
@Test("the axes give the same result from many context nodes (shared cache)")
func test_manyContexts() throws {
// Exercises the shared per-query cache across context nodes. The path is a
// deduplicated node-set: every x except the first appears in some node's
// following set, so the union is the 49 later x elements.
let xml = "<r>" + String(repeating: "<x/>", count: 50) + "</r>"
let total = try Int(PureXML.XPath.Query("count(//x/following::x)").value(at: PureXML.parseTree(xml)).number)
#expect(total == 49)
}
}