How salsa-rs/salsa works
Main Components
• Query Definitions – This includes both Input queries (the base inputs) and Function queries (which compute derived values). In salsa, each query is essentially defined as a function mapping a “key” to a “value.”
• Runtime / Database Core – In the src directory you see files like database.rs, database_impl.rs, runtime.rs, and various modules handling dependency graphs and memoization. This forms the core where queries are stored, tracked, and re-executed as needed.
• Dependency Graph & Incrementality – Components inside src (e.g., dependency_graph.rs) and modules in book/src/plumbing indicate that the system uses a dependency graph to determine which memoized results to invalidate.
• Macro Components – The components/salsa-macros and components/salsa-macro-rules directories contain macros that generate boilerplate code to facilitate the query system. These are essential in wiring together the input and tracked computations.
• Testing & Examples – Though not directly part of the runtime, the tests and examples (e.g., in examples/calc and tests/*) illustrate usage patterns and provide validation of the system design.
Relationships and Interactions
• The API Layer (Query Definitions): Developers define queries via macros from salsa-macros and salsa-macro-rules. These macros generate the code that interacts with the core runtime.
• The Runtime / Database Core: Once queries are defined and the program is running, the core (database_impl.rs, runtime modules, etc.) maintains a dependency graph, memo table, and incremental update logic. Every query call goes through this layer.
Architectural Patterns and Design Principles
• Incremental Computation Pattern: Memoization and selective recomputation are key. Emphasize that the system computes queries on-demand and only recomputes when necessary.
• Separation between Query Definition and Query Execution: There’s a clear boundary between how queries are declared (using macros and annotated functions) and how they are executed/managed by the runtime.
• Dependency Tracking: An explicit dependency graph exists that maintains the relationships between queries, showing how edges exist from an input’s changes to the function queries that need to re-evaluate.
• Extensibility: With components split into multiple Cargo packages (the macros, the core library, etc.), the system is modular and extensible.
Relevant Technologies and Tools
• Rust as the implementation language.
• Cargo for dependency management and compilation (highlight Cargo.toml and build scripts).
• GitHub Actions workflows (showing testing and documentation builds) might be noted on the periphery to signal CI integration.
• Book and examples as educational resources for how the architecture is intended to be used.
Specific Elements
• A central “Runtime/Database” block responsible for:
– Maintaining memoized results.
– Managing the incremental recomputation.
– Hosting the dependency graph (which can be a subcomponent inside the runtime).
– From the client code into the “Query API.”
– From there into the “Runtime/Database” where the dependency graph is updated.
– Back to the client code when values are returned.
• Optionally, a peripheral block to indicate CI/Build & Testing processes inspired by the workflows and tests directories.
• All major components: query definitions (inputs/functions), macros for code generation, runtime/database core, dependency graph for incremental computations, and supporting examples/tests.