← Contents

Chapter 30

AST Serialization and the Precompiled Parse

Parsing is not free, and a program that pulls in a dozen modules pays for all twelve on every run before it does any work of its own. Every implementation of every language eventually answers that with a precompilation format. This one has both an easier version of the problem and a harder one.

Raku++ executes by walking a tree, so the tree already is the compiled form; there is nothing further to compile it into. That makes caching straightforward in one sense — store the tree — and delicate in another, because a stored tree must be indistinguishable from a freshly parsed one.

The format

// src/AstSerial.h
inline constexpr uint32_t kAstSerialVersion = 62;
struct AstSerialError { std::string msg; };
std::string serializeAst(const Program& prog, bool stripLines = false);
void deserializeAst(const std::string& blob, Program& out);

A self-describing byte string with a header: the four bytes RKAS, the version, then the tree, with counts, kinds and line numbers as one-byte varints where they are small. The version constant is bumped whenever the encoding or the AST changes shape, and an entry carrying a different version is ignored, never reinterpreted. It was 17 when this chapter was first written and is 62 now. The steps the header comments on tell one story more than any other: a field the parser consumes and stores nowhere else — a trait, a smiley, a capture name — was added to a node, and a cached module came back without it until the visitor listed it.

stripLines writes 0 wherever a node's line would go, so two programs that differ only in layout serialize to the same bytes. That is the formatter's semantic gate (Chapter 39): format, re-parse, compare blobs. The cache leaves it off, because backtraces read the lines.

Two properties of the design are load-bearing.

Both directions are driven by one visitor per node type. A field cannot be written but not read, which is the failure mode that makes a format like this quietly wrong rather than loudly broken. Adding a field to SubDecl and forgetting the reader is not possible; the single visitor handles both.

The mutable per-node caches are deliberately not stored.

Binary::simpleOp, specialArm, fastShape, litVal, typedTree
Unary::evalPath
Param::whereStatic, whereCode
Index::fastShape, litIdx
NumLit::cacheN, cacheD
Block::hoistNeed
StrLit::nfcDone

Each has an "undecided" sentinel and is rebuilt lazily on first evaluation (Chapter 19), so a loaded tree behaves identically to a freshly parsed one — it just has not warmed up yet. Storing them would be both larger and more fragile, since litVal and whereCode are pointers.

Everything else round-trips, including line and label, because diagnostics depend on them.

Two independent switches

rakupp --precomp-modules=on    # cache the parse of `use`d modules
rakupp --precomp-files=on      # cache the main program's own parse
rakupp --precomp-info          # what is on, where it lives, what it holds
rakupp --precomp-clean         # empty it (always safe)

Both are off by default — nothing is written to disk until asked — and they are separate because they are worth very different amounts.

Modules. A dependency tree is a lot of source and none of it changes between runs:

no cachecached
use XML (10 files, 1,110 lines)16.0 ms5.7 ms

Files. A script's own parse is already sub-millisecond, and the few- millisecond floor of a small program is process startup, not parsing:

bare fileno cachecachedsaved
50 lines2.8 ms2.4 ms0.4 ms
1,000 lines10.0 ms5.1 ms4.9 ms
20,000 lines158.8 ms66.5 ms92.3 ms

Across the twenty-two fastest example programs, turning files on made no measurable difference at all. There is also a cost on the run that writes an entry — about 22 milliseconds at 20,000 lines — so for a script run once, files caching is a small net loss.

If you enable one, enable modules. That asymmetry is precisely why these are two switches rather than one.

What invalidates an entry

This is the interesting part, and it is where the naive design would be wrong.

// src/Interpreter.h
bool precompLoadProgram(const std::string& srcPath, const std::string& src,
                        const std::vector<std::string>& searchPath,
                        Program& out, std::string& finishOut);
void precompStoreProgram(const std::string& srcPath, const std::string& src,
                         const std::vector<std::string>& searchPath,
                         const Program& prog, const std::string& finish,
                         const std::vector<std::pair<std::string,
                                                     std::string>>& deps);

An entry is valid only while four things still hold.

The source has not changed. Content-validated, not timestamp-validated.

The rakupp binary is the same one. A tree from another build may not match this build's node shapes.

The search path is the same. This is the one people do not expect, and it is in the signature for a reason: the search path decides which file a use resolves to for operator scanning, so the same source under a different -I can legitimately parse differently.

The operators of everything it uses are unchanged. This is the deepest one. A module that gains or loses an operator declaration changes how this file parses, without this file changing at all (Chapter 6). So the parser records every source it scanned:

// src/Parser.h
std::vector<std::pair<std::string, std::string>> opScanned_;

and those pairs go into the entry as dependencies. It is the same list the parser needed anyway; making it a cache key was nearly free.

Where it lives, and what it reports

Settings persist in a small config file under the user's config directory; RAKUPP_PRECOMP_MODULES and RAKUPP_PRECOMP_FILES override for one invocation, and RAKUPP_NO_PRECOMP=1 forces both off.

// src/Interpreter.h
struct PrecompEntry {
    std::string source; unsigned long long bytes; bool usable; bool orphan;
};
std::vector<PrecompEntry> precompCacheList();
std::pair<size_t, unsigned long long> precompCacheClear();

The orphan flag distinguishes the one cache state that is pure garbage from the ones that are merely misses waiting to happen: the source file is gone, so the entry can never be reused or rewritten. Everything else is derived data, which is why clearing the cache is always safe.

What is not cached

Only the parse. A module's top-level declarations and its BEGIN blocks still execute on every run, which is roughly the 30% of module load time that is not parsing.

Rakudo goes further: its .precomp serialises the objects that compile-time code produced, so BEGIN runs once per compile rather than once per run. Matching that would mean serialising live runtime state — class registries, closures, whatever a BEGIN block built — which is a different and much larger project.

A compiled binary now does a narrow version of it, and the narrowness is the point. --exe, --aot and --bundle run the program's BEGIN blocks and constant initializers while building and embed each result that is plain data — one whose .raku evaluates back to an equal value of the same type — as that Raku text, substituted for the code that computed it (Chapter 25). No live state is serialised; anything that is not plain data still runs at startup. The cache does none of this.

Compared with the neighbours:

what it storeswhere
Raku++the ASTa central content-validated directory
Rakudo .precompbytecode plus compile-time objectsbeside the source
Python __pycache__bytecodebeside the source

Storing entries centrally rather than beside the source is what makes caching the main program defensible at all. Python never caches __main__, and the usual objection is that it would litter the source tree; that objection does not apply here.

The other consumer: embedded modules

The same serialisation carries modules inside a compiled binary (Chapter 25):

// src/Interpreter.h
struct BundledModule {
    std::string name, blob, finish, src;
    /* … the distribution's key, META6 and resource files … */
};
void rakuppRegisterModule(const std::string& name, const char* blob,
                          size_t blobLen, const std::string& finish);

collectModuleGraph resolves the transitive use graph at build time and serialises each module, dependencies first. loadModule consults the embedded table before the disk.

The format has two smaller consumers inside --exe as well. A statement a native module routine cannot compile is serialised on its own, embedded as bytes, and read back once at run time for the interpreter to execute (rtAotStmt, rtAotNode). And a bundled program's native routine bodies are attached only if the tree the binary parses at startup serializes to the same bytes they were compiled from — the blob's fingerprint is the check that the two parses agree.

That the cache format and the embedding format are the same format is not a coincidence — it is why a bug in either is found twice as fast.

The AOT emitter, and what it adds

--aot is the other consumer of this format, and it is worth being clear that it is this format:

// src/Ast.h
struct AstEmitError { std::string msg; };
void emitAstProgram(const Program& prog, std::ostream& out,
                    const std::string& fileName, const std::string& finish,
                    const std::vector<BundledModule>& mods);

What emitAstProgram adds is the wrapper: it calls serializeAst, writes the blob out as a kAst byte array, and generates a main that calls deserializeAst at startup. One encoding, two consumers — the cache reads it from disk and the binary carries it inside itself.

It used to be genuinely different: C++ source with one builder function per node, no reader needed because the compiler was the reader. That is the version this section used to contrast with, and it was replaced because listing each node's fields by hand meant a field nobody listed silently did not survive. Chapter 25 tells that story. The lesson it leaves here is the argument for the visitor: a writer and a reader that are the same source line cannot disagree about what a node contains, and two hand-written lists always eventually can.

Both fail soft. An unserialisable module is left out of the binary and loaded from disk; a tree the format cannot carry makes --aot fall back to bundling. Neither produces a wrong tree.

That shared property is the design rule worth taking away: a derived-data mechanism should degrade to recomputation, never to a guess. Every failure mode in this chapter — a version mismatch, a changed dependency, a missing source, an unhandled node — ends in "parse it again", which is slower and correct.