Skip to content
Merged
Show file tree
Hide file tree
Changes from 8 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions docs/zh/design/incremental-parse.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,16 @@ Preamble 编译为 PCH 文件后缓存在磁盘上。后续编译加载 PCH 后
- 依赖快照(`DepsSnapshot`,见下文)
- 与 PCH 配对存储、共享生命周期的 preamble 状态 blob 的句柄:构建时提取的 preamble 符号索引和功能状态(document links、非活跃区域、未闭合条件栈),以内存映射 FlatBuffer 形式打开、按需懒查询(见[符号索引](symbol-index.md))

### Preamble 状态的预计算

Preamble 分离带来的不只是编译加速,还有一个容易被忽视的性质:preamble 一旦编译成 PCH,它的内容在 PCH 的整个生命周期内不再变化。而代价是,主文件的编译加载 PCH 后就看不到这个区域了——preamble 区的指令、token 流都被 PCH 吞掉,对活 AST 而言是个黑盒。如果每个功能都在请求时各自想办法绕过这个黑盒,代码会碎成一地特判。

clice 的做法是抓住 PCH 构建的那一刻——preamble 唯一一次拥有完整活 AST 的时机——把这个区域的功能结果一次性算好:符号索引、document links、非活跃区域、未闭合条件栈,全部序列化进与 PCH 配对的状态 blob。之后的每次请求,功能层把预计算结果与主文件的实时结果合并:document links 是两段拼接,跳转和引用是 overlay 查询。预计算结果的有效期与 PCH 相同,不需要任何独立的失效逻辑——preamble 变了,PCH 和 blob 一起重建。

这背后是一条值得明确的分界:**可变的内容由活 AST 响应,不可变的内容由预计算结果响应,两者按功能各自定义合并方式**。它也回答了一个曾经纠结过的设计问题——要不要把 preamble 状态传给主文件编译、让它参与语义层的构建?答案是不要:能序列化传递的只有行级的结果数据,永远拼不回节点级的 AST 结构;行级数据的正确用法就是预计算加合并,不需要绕经语义层。新功能想覆盖 preamble 区域时(比如 preamble 区的 semantic tokens),做法也相同:在 PCH 构建侧算出结果行加入 blob,再定义与主文件结果的合并方式。

沿这条分界还能走得更远。bound 不必永远固定在 include 块的结尾:对上万行的巨型源文件,或触发 Clang 病态行为(如巨型常量数组)的代码,可以把缓存边界推进到文件更深处——由用户指定或启发式选择。前缀包含真实代码也不破坏该机制,因为前缀的功能结果照样在 PCH 构建时算好;前缀越大,增量编译越便宜,预计算的红利越大。

### 两层失效检测

PCH 缓存了 preamble 中所有被 `#include` 的头文件的预处理结果。当任何一个依赖头文件的内容发生变化时,PCH 就已过时,需要重建。问题在于如何精确判断"内容是否真的变了"。
Expand Down
12 changes: 12 additions & 0 deletions docs/zh/design/symbol-index.md
Original file line number Diff line number Diff line change
Expand Up @@ -242,3 +242,15 @@ FileIndex 打开文件的实时覆盖层(来自内存中的 AST)
- ~~**PCH 导致的索引分裂**~~(已解决)。使用 PCH 优化时,一个文件的编译被分成两个阶段:先把 preamble 编译成 PCH,再用 PCH 编译文件的其余部分。PCH 吞掉了 bound 之前的一切——主文件的编译既看不到头文件的内容,也看不到 preamble 区自身的指令;而且打开缓冲区的 preamble 可能描述一个任何磁盘翻译单元都未曾以之索引过的编译上下文。

现在的方案是为每个 PCH 配对一个 preamble 状态 blob,由同一次 worker 构建在刚解析完的 preamble AST 仍在内存时产出(这是唯一无需完整反序列化 PCH 就能获得其索引的时机)。blob 携带 preamble 的完整符号索引——覆盖的每个头文件加上主文件的 preamble 区——以及每文件的内容与行表(用于位置换算)、document links、非活跃区域和未闭合条件栈。它与 PCH 一同存储、一同命中、一同淘汰,以内存映射 FlatBuffer 形式打开,查询无需反序列化。打开文件把这些 blob 作为 overlay 叠加到索引查询上:集合查询与磁盘分片取并集(相同行按位置坍缩),单答案查询优先 overlay,缓冲区 preamble 区的游标经 blob 的主文件条目解析。这使得后台索引尚未(或无法)覆盖其翻译单元的打开文件仍能正常导航,查询结果也忠实于未保存的 preamble 编辑。

## 未来方向:只读模式

索引目前的定位是服务跨文件导航——一份为"符号在哪里"而设计的数据。但沿着预计算的思路走到底,会看到一个更大的可能性:当文件没有被修改时,整个文件都是不可变内容,理论上不需要构建任何 AST,从磁盘索引就能直接响应请求。

设想用户打开一个干净的文件,只是浏览、跳转、查引用。这些信息后台索引早已算过一遍,为一次只读访问重新构建完整 AST 是纯粹的浪费。只读模式下,服务器读索引即可响应——无 AST、无 PCH、近乎零启动成本。用户开始编辑时才升级到实时编译会话;停止编辑且内容回到已索引的状态后,又可以降回索引响应。响应的来源在"磁盘索引 → 预计算 preamble 加实时尾部 → 完整实时 AST"之间随内容的可变程度滑动,对客户端完全透明。

前提是索引的 schema 从"导航所需"扩展到"响应 LSP 请求所必要的全部信息"——不多存,也不少存。这远比想象的紧凑:AST 是为编译设计的,而响应一次 hover、渲染一屏 semantic tokens 所需要的只是提炼后的少量行。远程与 Web 环境是这个模式的直接受益者:静态托管一份索引,就能提供代码浏览级别的完整语言服务。

这与微软的 LSIF、Sourcegraph 的 SCIP 思路同源——都是预计算的代码智能快照——但定位不同。LSIF/SCIP 是编译无关的通用交换格式,是纯静态的终点;clice 的索引为 C++ 特化(编译上下文区分、内容寻址去重、preamble 分层),而且不是终点,是连续谱的一端——静态快照与实时 AST 之间可以合并与切换,这是通用格式做不到的。

统一语义层的重构已经为这条路铺了一段:功能实现与数据来源解耦了。semantic tokens 如今是"在表上渲染"而不是"在 AST 上现算",而这张表来自实时构建还是磁盘反序列化,对渲染逻辑是透明的。schema 具体要为哪些功能存哪些行、只读与实时会话之间的升降级如何判定,这些留到第一个真实消费者落地时再固化。
7 changes: 7 additions & 0 deletions src/compile/compilation_unit.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -403,6 +403,13 @@ TemplateResolver& CompilationUnitRef::resolver() {
return *self->resolver;
}

const Semantics& CompilationUnitRef::semantics() {
if(!self->semantics_cache) {
self->semantics_cache = std::make_unique<Semantics>(Semantics::build(*this));
}
return *self->semantics_cache;
}

clang::ASTContext& CompilationUnitRef::context() {
return self->instance->getASTContext();
}
Expand Down
6 changes: 6 additions & 0 deletions src/compile/compilation_unit.h
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@

namespace clice {

class Semantics;

namespace index {

// Temporary in-header definition during migration.
Expand Down Expand Up @@ -250,6 +252,10 @@ class CompilationUnitRef {

TemplateResolver& resolver();

/// The semantic map of the interested file (token → owning node), built
/// lazily on first use and cached for the unit's lifetime.
const Semantics& semantics();

llvm::DenseMap<clang::FileID, Directive>& directives();

clang::TranslationUnitDecl* tu();
Expand Down
4 changes: 4 additions & 0 deletions src/compile/implement.h
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

#include "compile/compilation_unit.h"
#include "compile/diagnostic.h"
#include "semantic/semantics.h"

#include "clang/Frontend/CompilerInstance.h"
#include "clang/Frontend/FrontendActions.h"
Expand Down Expand Up @@ -71,6 +72,9 @@ struct CompilationUnitRef::Self {
/// The template resolver used to resolve dependent name.
std::optional<TemplateResolver> resolver;

/// Lazily built semantic map, see CompilationUnitRef::semantics().
std::unique_ptr<Semantics> semantics_cache;

/// Token information collected during the preprocessing.
std::optional<clang::syntax::TokenBuffer> buffer;

Expand Down
Loading
Loading