Crate gluon_salsa

The salsa crate is a crate for incremental recomputation. It permits you to define a “database” of queries with both inputs and values derived from those inputs; as you set the inputs, you can re-execute the derived queries and it will try to re-use results from previous invocations as appropriate.

Modules

debug

Debugging APIs: these are meant for use when unit-testing or debugging your application but aren’t ordinarily needed.

Macros

cast_owned_db

TODO

Structs

CycleError

The error returned when a query could not be resolved due to a cycle

DatabaseKeyIndex

An integer that uniquely identifies a particular query instance within the database. Used to track dependencies between queries. Fully ordered and equatable but those orderings are arbitrary, and meant to be used only for inserting into maps and the like.

Durability

Describes how likely a value is to change – how “durable” it is. By default, inputs have Durability::LOW and interned values have Durability::HIGH. But inputs can be explicitly set with other durabilities.

Event

The Event struct identifies various notable things that can occur during salsa execution. Instances of this struct are given to salsa_event.

ForkState

Forker

Returned from calling ParallelDatabase::forker. Used to fork on a database so that multiple queries can run concurrently

InternId

The “raw-id” is used for interned keys in salsa – it is basically a newtype’d u32. Typically, it is wrapped in a type of your own devising. For more information about interned keys, see the interned key RFC.

OwnedDb

Encapsulates a mutable reference to a database while only giving out shared references. Use for asynchronous queries to make the database references passed Send

QueryTable

Return value from the query method on Database. Gives access to various less common operations on queries.

QueryTableMut

Return value from the query_mut method on Database. Gives access to the set method, notably, that is used to set the value of an input query.

Revision

A unique identifier for the current version of the database; each time an input is changed, the revision number is incremented. Revision is used internally to track which values may need to be recomputed, but is not something you should have to interact with directly as a user of salsa.

Runtime

The salsa runtime stores the storage for all queries as well as tracking the query stack and dependencies between cycles.

RuntimeId

A unique identifier for a particular runtime. Each time you create a snapshot, a fresh RuntimeId is generated. Once a snapshot is complete, its RuntimeId may potentially be re-used.

Snapshot

Simple wrapper struct that takes ownership of a database DB and only gives &self access to it. See the snapshot method for more details.

Storage

Stores the cached results and dependency information for all the queries defined on your salsa database. Also embeds a Runtime which is used to manage query execution. Every database must include a storage: Storage<Self> field.

SweepStrategy

The sweep strategy controls what data we will keep/discard when we do a GC-sweep. The default (SweepStrategy::default) is a no-op, use SweepStrategy::discard_outdated constructor or discard_* and sweep_* builder functions to construct useful strategies.

Enums

EventKind

An enum identifying the various kinds of events that can occur.

Traits

Database

The base trait which your “query context” must implement. Gives access to the salsa runtime, which you must embed into your query context (along with whatever other state you may require).

InternKey

Trait implemented for the “key” that results from a #[salsa::intern] query. This is basically meant to be a “newtype”’d u32.

ParallelDatabase

Indicates a database that also supports parallel query evaluation. All of Salsa’s base query support is capable of parallel execution, but for it to work, your query key/value types must also be Send, as must any additional data in your database.

Query

Trait implements by all of the “special types” associated with each of your queries.

QueryBase

Trait implements by all of the “special types” associated with each of your queries.

QueryDb

Trait implements by all of the “special types” associated with each of your queries.

Functions

forker

TODO

Type Aliases

BoxFuture

A boxed future used in the salsa traits