Jon Ross-Perkins
4923445e3a
We frequently want to operate on singletons. Per discussion, drop `Singleton` to make the code shorter. This started off as wanting to write `inst_id.is_error()`, but the dependency relationship between ids.h and singleton_insts.h would require some kind of delayed evaluation to allow the implementation to remain in headers (which I suspect is helpful to have for inlining). I could have added something like `IsErrorInst`, forward declared in ids.h and defined in singleton_insts.h (which would always be included by typed_insts.h), but the template approach felt like a decent balance between (a) removing the boilerplate `::SingletonInstId`, (b) understandability, (c) still visually mirroring if we immediately return a singleton, and (d) flexibility for more than just `ErrorInst`. But TBH I'd probably still have written `is_error()` if it didn't require addressing the cross-header cycle. Then I tried `SemIR::InstId::Is<SemIR::ErrorInst>`, which generally worked with types but generated the complaint that it didn't shorten *all* singleton uses. So pulling back on `::Is`, and instead just dropping `Singleton`.
Toolchain architecture
Table of contents
Goals
The toolchain represents the production portion of Carbon. At a high level, the toolchain's top priorities are:
- Correctness.
- Quality of generated code, including performance.
- Compilation performance.
- Quality of diagnostics for incorrect or questionable code.
TODO: Add an expanded document that details the goals and priorities and link to it here.
High-level architecture
The main components are:
-
Driver: Provides commands and ties together compilation flow.
-
Diagnostics: Produces diagnostic output.
-
Compilation flow:
- Source: Load the file into a SourceBuffer.
- Lex: Transform a SourceBuffer into a Lex::TokenizedBuffer.
- Parse: Transform a TokenizedBuffer into a Parse::Tree.
- Check: Transform a Tree to produce SemIR::File.
- Lower: Transform the SemIR to an LLVM Module.
- CodeGen: Transform the LLVM Module into an Object File.
Design patterns
A few common design patterns are:
-
Distinct steps: Each step of processing produces an output structure, avoiding callbacks passing data between structures.
-
For example, the parser takes a
Lex::TokenizedBufferas input and produces aParse::Treeas output. -
Performance: It should yield better locality versus a callback approach.
-
Understandability: Each step has a clear input and output, versus callbacks which obscure the flow of data.
-
-
Vectorized storage: Data is stored in vectors and flyweights are passed around, avoiding more typical heap allocation with pointers.
-
For example, the parse tree is stored as a
llvm::SmallVector<Parse::Tree::NodeImpl>indexed byParse::Nodewhich wraps anint32_t. -
Performance: Vectorization both minimizes memory allocation overhead and enables better read caching because adjacent entries will be cached together.
-
-
Iterative processing: We rely on state stacks and iterative loops for parsing, avoiding recursive function calls.
-
For example, the parser has a
Parse::Stateenum tracked instate_stack_, and loops inParse::Tree::Parse. -
Scalability: Complex code must not cause recursion issues. We have experience in Clang seeing stack frame recursion limits being hit in unexpected ways, and non-recursive approaches largely avoid that risk.
-
See also Idioms for abbreviations and more implementation techniques.
Adding features
We have a walkthrough for adding features.