Salsa

https://docs.rs/salsa/latest/
Admin
Salsa is a Rust framework for building incremental computations and query systems with automatic...
Tokens:113,108
Snippets:777
Trust Score:9.7
Update:14 hours ago
Show doc for...
Tokens:
Raw
### Example: Defining a Salsa database with #[salsa::db]

Source: https://docs.rs/salsa/latest/salsa/attr.db.html

Complete example from the documentation showing a struct with a `storage` field, a database trait, and implementations of that trait and `salsa::Database`, all annotated with `#[salsa::db]`.

```rust
#[salsa::db]
#[derive(Clone, Default)]
struct MyDatabase {
    storage: salsa::Storage<Self>,
}

#[salsa::db]
trait MyDatabaseView: salsa::Database {}

#[salsa::db]
impl MyDatabaseView for MyDatabase {}

#[salsa::db]
impl salsa::Database for MyDatabase {}
```

--------------------------------

### Example: Using #[salsa::accumulator] and #[salsa::tracked]

Source: https://docs.rs/salsa/latest/salsa/attr.accumulator.html

Example from the documentation showing how to define an accumulator struct and use it in a tracked function. The struct must implement Send + Sync + UnwindSafe + 'static. The example uses `salsa::Accumulator::accumulate` to add a diagnostic.

```rust
#[salsa::accumulator]
struct Diagnostic(String);

#[salsa::tracked]
fn check(db: &dyn salsa::Database) {
    salsa::Accumulator::accumulate(Diagnostic("something went wrong".into()), db);
}
```

--------------------------------

### Example: #[salsa::interned(debug)] struct Name

Source: https://docs.rs/salsa/latest/salsa/attr.interned.html

Example of using the interned attribute with the debug option and field attributes `#[returns(deref)]`, `#[returns(copy)]`, and `#[get(disambiguator)]`.

```rust
#[salsa::interned(debug)]
struct Name<'db> {
    #[returns(deref)]
    text: String,
    #[returns(copy)]
    #[get(disambiguator)]
    index: u32,
}
```

--------------------------------

### DatabaseImpl::new

Source: https://docs.rs/salsa/latest/salsa/struct.DatabaseImpl.html

Creates a new database instance. Equivalent to Self::default.

```APIDOC
## [Rust] DatabaseImpl::new

### Description
Creates a new database instance. Equivalent to `Self::default`.

### Method
`pub fn new() -> Self`

### Parameters
None.

### Returns
- `Self` - A new `DatabaseImpl` instance.

### Example
```rust
let db = DatabaseImpl::new();
```
```

--------------------------------

### Persistence module: OriginAndExtra::new and QueryEdge serialization

Source: https://docs.rs/salsa/latest/src/salsa/zalsa_local.rs.html

Under the `persistence` feature, defines `OriginAndExtra::new` to construct from a `PersistentQueryOrigin` and extra, and `QueryEdge::raw_key` to create a `DatabaseKeyIndex`. Also implements `serde::Serialize` and `Deserialize` for `QueryEdge`.

```rust
#[cfg(feature = "persistence")]
pub(crate) mod persistence {
    #[cfg(test)]
    use super::QueryOriginRef;
    use super::{OriginAndExtra, QueryEdge, QueryEdges, QueryRevisions, QueryRevisionsExtra};
    use crate::DatabaseKeyIndex;
    use crate::sync::atomic::{AtomicBool, Ordering};
    use crate::{Durability, Revision};

    impl OriginAndExtra {
        pub(crate) fn new(origin: PersistentQueryOrigin, extra: QueryRevisionsExtra) -> Self {
            match origin {
                PersistentQueryOrigin::Assigned(key) => match extra.0 {
                    Some(extra) => Self::assigned_with_extra(key, extra),
                    None => Self::assigned(key),
                },
                PersistentQueryOrigin::Derived(edges) => {
                    Self::derived(edges.iter().copied(), extra)
                }
                PersistentQueryOrigin::DerivedUntracked(edges) => {
                    Self::derived_untracked(edges.iter().copied(), extra)
                }
            }
        }
    }

    impl QueryEdge {
        const fn raw_key(self) -> DatabaseKeyIndex {
            DatabaseKeyIndex::new(self.ingredient, self.id())
        }
    }

    impl serde::Serialize for QueryEdge {
        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
        where
            S: serde::Serializer,
        {
            serde::Serialize::serialize(&self.raw_key(), serializer)
        }
    }

    impl<'de> serde::Deserialize<'de> for QueryEdge {
        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
        where
            D: serde::Deserializer<'de>,
        {
            let key: DatabaseKeyIndex = serde::Deserialize::deserialize(deserializer)?;
            let id = key.key_index();

            Ok(QueryEdge {
                index: id.index(),
            })
        }
    }
}
```

--------------------------------

### DatabaseImpl::unwind_if_revision_cancelled

Source: https://docs.rs/salsa/latest/salsa/struct.DatabaseImpl.html

Starts unwinding the stack if the current revision is cancelled.

```APIDOC
## [Rust] DatabaseImpl::unwind_if_revision_cancelled

### Description
Starts unwinding the stack if the current revision is cancelled.

### Method
`fn unwind_if_revision_cancelled(&self)`

### Parameters
None.

### Returns
- `()` - No return value.

### Example
```rust
db.unwind_if_revision_cancelled();
```
```

--------------------------------

### QueryEdges constructors and methods

Source: https://docs.rs/salsa/latest/src/salsa/zalsa_local.rs.html

Implements constructors packed() and wide(), and methods len(), allocation_size(), iter(), iter_outputs(), and is_packed(). len() and allocation_size() are cfg-gated, and iter_outputs() returns only output edges.

```rust
impl<'a> QueryEdges<'a> {
    const fn packed(edges: &'a [PackedQueryEdge]) -> Self {
        QueryEdges {
            data: QueryEdgesData::Packed(edges),
        }
    }

    const fn wide(edges: &'a [QueryEdge]) -> Self {
        QueryEdges {
            data: QueryEdgesData::Wide(edges),
        }
    }

    #[cfg(feature = "accumulator")]
    pub(crate) const fn len(self) -> usize {
        match self.data {
            QueryEdgesData::Packed(edges) => edges.len(),
            QueryEdgesData::Wide(edges) => edges.len(),
        }
    }

    #[cfg(test)]
    pub(crate) const fn allocation_size(self) -> usize {
        match self.data {
            QueryEdgesData::Packed(edges) => std::mem::size_of_val(edges),
            QueryEdgesData::Wide(edges) => std::mem::size_of_val(edges),
        }
    }

    pub(crate) fn iter(self) -> QueryEdgeIter<'a> {
        let data = match self.data {
            QueryEdgesData::Packed(edges) => QueryEdgeIterData::Packed(edges.iter()),
            QueryEdgesData::Wide(edges) => QueryEdgeIterData::Wide(edges.iter()),
        };

        QueryEdgeIter { data }
    }

    pub(crate) fn iter_outputs(self) -> impl DoubleEndedIterator<Item = QueryEdge> + use<'a> {
        let wide_edges = match self.data {
            QueryEdgesData::Packed(_) => &[][..],
            QueryEdgesData::Wide(edges) => edges,
        };

        wide_edges
            .iter()
            .copied()
            .filter(|edge| matches!(edge.kind(), QueryEdgeKind::Output))
    }

    #[cfg(test)]
    const fn is_packed(self) -> bool {
        matches!(self.data, QueryEdgesData::Packed(_))
    }
}
```

--------------------------------

### Derive SalsaValue for a struct with a lifetime parameter

Source: https://docs.rs/salsa/latest/salsa/derive.SalsaValue.html

Example of deriving `SalsaValue` for a struct with a lifetime parameter and a field of type `MyInterned<'db>`.

```rust
#[derive(salsa::SalsaValue)]
struct QueryValue<'db> {
    item: MyInterned<'db>,
}
```

--------------------------------

### Insert jar and register ingredients

Source: https://docs.rs/salsa/latest/src/salsa/zalsa.rs.html

Inserts a jar into the Zalsa instance, creating ingredients and registering those that require reset for new revisions. Asserts that ingredient indices match predictions.

```rust
fn insert_jar(&mut self, jar: ErasedJar) {
    let jar_type_id = (jar.type_id)();

    let index = IngredientIndex::new(self.ingredients_vec.len() as u32);

    if self.jar_map.contains_key(&jar_type_id) {
        return;
    }

    let ingredients = (jar.create_ingredients)(self, index);
    for ingredient in ingredients {
        let expected_index = ingredient.ingredient_index();
        if ingredient.requires_reset_for_new_revision() {
            self.ingredients_requiring_reset.push(expected_index);
        }

        self.ingredients_vec.push(ingredient);

        let actual_index = self.ingredients_vec.len() - 1;
        assert_eq!(
            expected_index.as_u32() as usize,
            actual_index,
            "ingredient `{:?}` was predicted to have index `{:?}` but actually has index `{:?}`",
            self.ingredients_vec[actual_index],
            expected_index.as_u32(),
            actual_index,
        );
    }
}
```

--------------------------------

### Cancellation check and unwind

Source: https://docs.rs/salsa/latest/src/salsa/zalsa.rs.html

Starts unwinding the stack if the current revision is cancelled. Can be called by query implementations to speed up cancellation propagation; cancellation is automatically triggered on any query invocation.

```rust
#[inline]
pub(crate) fn unwind_if_revision_cancelled(&self, zalsa_local: &ZalsaLocal) {
    self.event(&|| crate::Event::new(crate::EventKind::WillCheckCancellation));
    if zalsa_local.should_trigger_local_cancellation() {
        zalsa_local.unwind_cancelled();
    }
    if self.runtime().load_cancellation_flag() {
        zalsa_local.unwind_pending_write();
    }
}
```

--------------------------------

### Persistence module: serialization and deserialization

Source: https://docs.rs/salsa/latest/src/salsa/database.rs.html

Implements `serde::Serialize` and `serde::Deserialize` for `dyn Database`, including `SerializeDatabase` and `SerializeIngredients` to serialize the database state. Deserialization modifies the database in-place.

```rust
#[cfg(feature = "persistence")]
mod persistence {
    use crate::plumbing::Ingredient;
    use crate::zalsa::Zalsa;
    use crate::{Database, IngredientIndex, Runtime};

    use std::fmt;

    use serde::de::{self, DeserializeSeed, SeqAccess};
    use serde::ser::SerializeMap;

    impl dyn Database {
        /// Returns a type implementing [`serde::Serialize`], that can be used to serialize the
        /// current state of the database.
        ///
        /// Cancels other workers and waits for their database handles to be dropped.
        pub fn as_serialize(&mut self) -> impl serde::Serialize + '_ {
            SerializeDatabase::new(self)
        }

        /// Deserialize the database using a [`serde::Deserializer`].
        ///
        /// This method will modify the database in-place based on the serialized data.
        pub fn deserialize<'db, D>(&mut self, deserializer: D) -> Result<(), D::Error>
        where
            D: serde::Deserializer<'db>,
        {
            DeserializeDatabase(self.zalsa_mut()).deserialize(deserializer)
        }
    }

    #[derive(serde::Serialize)]
    #[serde(rename = "Database")]
    pub struct SerializeDatabase<'db> {
        runtime: &'db Runtime,
        ingredients: SerializeIngredients<'db>,
    }

    impl<'db> SerializeDatabase<'db> {
        /// Acquires exclusive storage access for the lifetime of the serializer.
        fn new(db: &'db mut dyn Database) -> Self {
            let zalsa = db.zalsa_mut();
            Self {
                runtime: zalsa.runtime(),
                ingredients: SerializeIngredients(zalsa),
            }
        }
    }

    struct SerializeIngredients<'db>(&'db Zalsa);

    impl serde::Serialize for SerializeIngredients<'_> {
        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
        where
            S: serde::Serializer,
        {
            let SerializeIngredients(zalsa) = self;

            let mut ingredients = zalsa
                .ingredients()
                .filter(|ingredient| ingredient.should_serialize(zalsa))
                .collect::<Vec<_>>();

            // Ensure structs are serialized before tracked functions, as deserializing a
            // memo requires its input struct to have been deserialized.
            ingredients.sort_by_key(|ingredient| ingredient.jar_kind());

            let mut map = serializer.serialize_map(Some(ingredients.len()))?;
            for ingredient in ingredients {
                map.serialize_entry(
                    &ingredient.ingredient_index().as_u32(),
                    &SerializeIngredient(ingredient, zalsa),
                )?;
            }

            map.end()
        }
    }

    struct SerializeIngredient<'db>(&'db dyn Ingredient, &'db Zalsa);

    impl serde::Serialize for SerializeIngredient<'_> {
        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
        where
            S: serde::Serializer,
        {
            let mut result = None;
            let mut serializer = Some(serializer);

            // SAFETY: `SerializeDatabase::new` obtains exclusive storage access through `zalsa_mut`
            // and retains that borrow throughout serialization.
            unsafe {
                self.0.serialize(self.1, &mut |serialize| {
                    let serializer = serializer.take().expect(
                        "`Ingredient::serialize` must invoke the serialization callback only once",
                    );

                    result = Some(erased_serde::serialize(&serialize, serializer))
                })
            };
        }
    }
}
```

--------------------------------

### Derive SalsaValue with conditional proof for a generic field

Source: https://docs.rs/salsa/latest/salsa/derive.SalsaValue.html

Example of deriving `SalsaValue` for a generic struct where a field type does not implement `SalsaValue`, using `#[salsa_value(unsafe(prove(T: salsa::SalsaValue)))]` to add a conditional bound.

```rust
#[derive(salsa::SalsaValue)]
struct QueryValue<T> {
    #[salsa_value(unsafe(prove(T: salsa::SalsaValue)))]
    value: ForeignContainer<T>,
}
```

--------------------------------

### Revision and AtomicRevision implementation in revision.rs

Source: https://docs.rs/salsa/latest/src/salsa/revision.rs.html

Defines the `Revision` struct with methods for starting, incrementing, and converting to `usize`. Also defines `AtomicRevision` for atomic load/store operations and `OptionalAtomicRevision`. Includes serde serialization for the `persistence` feature.

```rust
use std::num::NonZeroUsize;

use crate::sync::atomic::{AtomicUsize, Ordering};

/// Value of the initial revision, as a u64. We don't use 0
/// because we want to use a `NonZeroUsize`.
const START: usize = 1;

/// 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.
#[derive(Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[repr(transparent)]
pub struct Revision {
    generation: NonZeroUsize,
}

impl Revision {
    #[inline]
    pub const fn max() -> Self {
        Self::from(usize::MAX)
    }

    #[inline]
    pub(crate) const fn start() -> Self {
        Self {
            // SAFETY: `START` is non-zero.
            generation: unsafe { NonZeroUsize::new_unchecked(START) },
        }
    }

    #[inline]
    pub(crate) const fn from(g: usize) -> Self {
        Self {
            generation: NonZeroUsize::new(g).unwrap(),
        }
    }

    #[inline]
    pub(crate) fn from_opt(g: usize) -> Option<Self> {
        NonZeroUsize::new(g).map(|generation| Self { generation })
    }

    #[inline]
    pub(crate) fn next(self) -> Revision {
        Self::from(self.generation.get() + 1)
    }

    #[inline]
    pub(crate) const fn as_usize(self) -> usize {
        self.generation.get()
    }
}

#[cfg(feature = "persistence")]
impl serde::Serialize for Revision {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serde::Serialize::serialize(&self.as_usize(), serializer)
    }
}

#[cfg(feature = "persistence")]
impl<'de> serde::Deserialize<'de> for Revision {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        serde::Deserialize::deserialize(deserializer).map(|generation| Self { generation })
    }
}

impl std::fmt::Debug for Revision {
    fn fmt(&self, fmt: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(fmt, "R{}", self.generation)
    }
}

#[derive(Debug)]
pub struct AtomicRevision {
    data: AtomicUsize,
}

#[cfg(feature = "persistence")]
impl serde::Serialize for AtomicRevision {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serde::Serialize::serialize(&self.data.load(Ordering::Relaxed), serializer)
    }
}

#[cfg(feature = "persistence")]
impl<'de> serde::Deserialize<'de> for AtomicRevision {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let revision: Revision = serde::Deserialize::deserialize(deserializer)?;
        Ok(Self::new(revision))
    }
}

impl From<Revision> for AtomicRevision {
    fn from(value: Revision) -> Self {
        Self {
            data: AtomicUsize::new(value.as_usize()),
        }
    }
}

impl AtomicRevision {
    pub const fn start() -> Self {
        Self {
            data: AtomicUsize::new(START),
        }
    }

    pub const fn new(revision: Revision) -> Self {
        Self {
            data: AtomicUsize::new(revision.as_usize()),
        }
    }

    #[inline]
    pub fn load(&self) -> Revision {
        Revision {
            // SAFETY: We know that the value is non-zero because we only ever store `START` which 1, or a
            // Revision which is guaranteed to be non-zero.
            generation: unsafe { NonZeroUsize::new_unchecked(self.data.load(Ordering::Acquire)) },
        }
    }

    pub fn store(&self, r: Revision) {
        self.data.store(r.as_usize(), Ordering::Release);
    }

    pub fn get_mut(&mut self) -> &mut Revision {
        // SAFETY: `Revision` is repr(transparent) over `NonZeroUsize`, we only ever store `NonZeroUsize` values, thus making this cast valid.
        unsafe { &mut *(self.data.get_mut() as *mut usize).cast::<Revision>() }
    }
}

impl Clone for AtomicRevision {
    fn clone(&self) -> Self {
        Self {
            data: AtomicUsize::new(self.load().as_usize()),
        }
    }
}

#[derive(Debug)]
pub(crate) struct OptionalAtomicRevision {
    data: AtomicUsize,
}

#[cfg(feature = "persistence")]
impl serde::Serialize for OptionalAtomicRevision {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serde::Serialize::serialize(&self.data.load(Ordering::Relaxed), serializer)
    }
}

#[cfg(feature = "persistence")]
impl<'de> serde::Deserialize<'de> for OptionalAtomicRevision {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let revision: Revision = serde::Deserialize::deserialize(deserializer)?;
        Ok(Self::new(revision))
    }
}

impl From<Revision> for OptionalAtomicRevision {
    fn from(value: Revision) -> Self {
        Self {
            data: AtomicUsize::new(value.as_usize()),
        }
    }
}

impl OptionalAtomicRevision {
    pub const fn start() -> Self {
        Self {
            data: AtomicUsize::new(START),
        }
    }

    pub const fn new(revision: Revision) -> Self {
        Self {
            data: AtomicUsize::new(revision.as_usize()),
        }
    }

    #[inline]
    pub fn load(&self) -> Revision {
        Revision {
            // SAFETY: We know that the value is non-zero because we only ever store `START` which 1, or a
            // Revision which is guaranteed to be non-zero.
            generation: unsafe { NonZeroUsize::new_unchecked(self.data.load(Ordering::Acquire)) },
        }
    }

    pub fn store(&self, r: Revision) {
        self.data.store(r.as_usize(), Ordering::Release);
    }

    pub fn get_mut(&mut self) -> &mut Revision {
        // SAFETY: `Revision` is repr(transparent) over `NonZeroUsize`, we only ever store `NonZeroUsize` values, thus making this cast valid.
        unsafe { &mut *(self.data.get_mut() as *mut usize).cast::<Revision>() }
    }
}

impl Clone for OptionalAtomicRevision {
    fn clone(&self) -> Self {
        Self {
            data: AtomicUsize::new(self.load().as_usize()),
        }
    }
}
```

--------------------------------

### StorageHandle and Storage definitions in storage.rs

Source: https://docs.rs/salsa/latest/src/salsa/storage.rs.html

Defines StorageHandle, Storage, and related types for managing database state. Includes Clone, Default, and Drop implementations, plus methods for creating storage and converting between handle and storage.

```rust
1//! Public API facades for the implementation details of [`Zalsa`] and [`ZalsaLocal`].
2use std::marker::PhantomData;
3use std::panic::RefUnwindSafe;
4
5use crate::sync::{Arc, Condvar, Mutex};
6use crate::zalsa::{ErasedJar, HasJar, Zalsa, ZalsaDatabase};
7use crate::zalsa_local::{self, ZalsaLocal};
8use crate::{Database, Event, EventKind};
9
10/// A handle to non-local database state.
11pub struct StorageHandle<Db> {
12    // Note: Drop order is important, zalsa_impl needs to drop before coordinate
13    /// Reference to the database.
14    zalsa_impl: Arc<Zalsa>,
15
16    // Note: Drop order is important, coordinate needs to drop after zalsa_impl
17    /// Coordination data for cancellation of other handles when `zalsa_mut` is called.
18    /// This could be stored in Zalsa but it makes things marginally cleaner to keep it separate.
19    coordinate: CoordinateDrop,
20
21    /// We store references to `Db`
22    phantom: PhantomData<fn() -> Db>,
23}
24
25impl<Db> Clone for StorageHandle<Db> {
26    fn clone(&self) -> Self {
27        *self.coordinate.clones.lock() += 1;
28
29        Self {
30            zalsa_impl: self.zalsa_impl.clone(),
31            coordinate: CoordinateDrop(Arc::clone(&self.coordinate)),
32            phantom: PhantomData,
33        }
34    }
35}
36
37impl<Db: Database> Default for StorageHandle<Db> {
38    fn default() -> Self {
39        Self::new(None)
40    }
41}
42
43impl<Db: Database> StorageHandle<Db> {
44    pub fn new(event_callback: Option<Box<dyn Fn(crate::Event) + Send + Sync + 'static>>) -> Self {
45        Self::with_jars(event_callback, Vec::new())
46    }
47
48    fn with_jars(
49        event_callback: Option<Box<dyn Fn(crate::Event) + Send + Sync + 'static>>,
50        jars: Vec<ErasedJar>,
51    ) -> Self {
52        Self {
53            zalsa_impl: Arc::new(Zalsa::new::<Db>(event_callback, jars)),
54            coordinate: CoordinateDrop(Arc::new(Coordinate {
55                clones: Mutex::new(1),
56                cvar: Default::default(),
57            })),
58            phantom: PhantomData,
59        }
60    }
61
62    pub fn into_storage(self) -> Storage<Db> {
63        Storage {
64            handle: self,
65            zalsa_local: ZalsaLocal::new(),
66        }
67    }
68}
69
70/// Access the "storage" of a Salsa database: this is an internal plumbing trait
71/// automatically implemented by `#[salsa::db]` applied to a struct.
72///
73/// # Safety
74///
/// The `storage` and `storage_mut` fields must both return a reference to the same
/// storage field which must be owned by `self`.
75pub unsafe trait HasStorage: Database + Sized {
76    fn storage(&self) -> &Storage<Self>;
77    fn storage_mut(&mut self) -> &mut Storage<Self>;
78}
79
80/// Concrete implementation of the [`Database`] trait with local state that can be used to drive computations.
81pub struct Storage<Db> {
82    handle: StorageHandle<Db>,
83
84    /// Per-thread state
85    zalsa_local: zalsa_local::ZalsaLocal,
86}
87
88impl<Db> Drop for Storage<Db> {
89    fn drop(&mut self) {
90        self.zalsa_local
91            .record_unfilled_pages(self.handle.zalsa_impl.table());
92    }
93}
94
95struct Coordinate {
96    /// Counter of the number of clones of actor. Begins at 1.
97    /// Incremented when cloned, decremented when dropped.
98    clones: Mutex<usize>,
99    cvar: Condvar,
100}
101
102// We cannot panic while holding a lock to `clones: Mutex<usize>` and therefore we cannot enter an
103// inconsistent state.
104impl RefUnwindSafe for Coordinate {}
105
106impl<Db: Database> Default for Storage<Db> {
107    fn default() -> Self {
108        Self::new(None)
109    }
110}
111
112impl<Db: Database> Storage<Db> {
113    /// Create a new database storage.
114    ///
115    /// The `event_callback` function is invoked by the salsa runtime at various points during execution.
116    pub fn new(event_callback: Option<Box<dyn Fn(crate::Event) + Send + Sync + 'static>>) -> Self {
117        Self {
118            handle: StorageHandle::new(event_callback),
119            zalsa_local: ZalsaLocal::new(),
120        }
121    }
122
123    /// Returns a builder for database storage.
124    pub fn builder() -> StorageBuilder<Db> {
125        StorageBuilder::default()
126    }
127
128    /// Convert this instance of [`Storage`] into a [`StorageHandle`].
129    ///
    /// This will discard the local state of this [`Storage`], thereby returning a value that
    /// is both [`Sync`] and [`std::panic::UnwindSafe`].
130    pub fn into_zalsa_handle(mut self) -> StorageHandle<Db> {
131        self.zalsa_local
            .record_unfilled_pages(self.handle.zalsa_impl.table());
132        let Self {
133            handle,
134            zalsa_local,
135        } = &mut self;
136        // Avoid rust's annoying destructure prevention rules for `Drop` types
137        // SAFETY: We forget `Self` afterwards to discard the original copy, and the destructure
```

--------------------------------

### Tracked impl block example with word_count and line_count

Source: https://docs.rs/salsa/latest/salsa/attr.tracked.html

Shows a Salsa input struct File with a tracked deref field, a tracked function word_count, and a tracked impl block with a tracked method line_count. The method takes self by value and the database parameter, and uses #[salsa::tracked(returns(copy))] to return a copy.

```rust
#[salsa::input]
struct File {
    #[returns(deref)]
    text: String,
}

#[salsa::tracked(returns(copy))]
fn word_count(db: &dyn salsa::Database, file: File) -> usize {
    file.text(db).split_whitespace().count()
}

#[salsa::tracked]
impl File {
    #[salsa::tracked(returns(copy))]
    fn line_count(self, db: &dyn salsa::Database) -> usize {
        self.text(db).lines().count()
    }
}
```

--------------------------------

### attach_allow_change function to attach database allowing changes

Source: https://docs.rs/salsa/latest/src/salsa/attach.rs.html

The `attach_allow_change` function attaches a database to the current thread, allowing a different database than currently attached. The original database is restored on return. It warns that switching databases can cause bugs and recommends using `attach` instead.

```rust
/// Attach the database to the current thread and execute `op`.
/// Allows a different database than currently attached. The original database
/// will be restored on return.
///
/// **Note:** Switching databases can cause bugs. If you do not intend to switch
/// databases, prefer [`attach`] which will panic if you accidentally do.
#[inline]
pub fn attach_allow_change<R, Db>(db: &Db, op: impl FnOnce() -> R) -> R
where
    Db: ?Sized + Database,
{
    ATTACHED.with(
        #[inline]
        |a| a.attach_allow_change(db, op),
    )
}

```

--------------------------------

### Derive Supertype macro usage

Source: https://docs.rs/salsa/latest/salsa/derive.Supertype.html

The `#[derive(Supertype)]` macro is applied to an enum to create a heterogeneous query key. The enum variants wrap Salsa structs, and the macro uses the wrapped struct's ID as the query key. The example shows an enum `Source` with `File` and `Symbol` variants, used as a parameter in a tracked function.

```rust
#[salsa::input]
struct File {
    #[returns(deref)]
    path: String,
}

#[salsa::interned]
struct Symbol<'db> {
    #[returns(deref)]
    name: String,
}

#[derive(Clone, Copy, PartialEq, Eq, Hash, salsa::Supertype)]
enum Source<'db> {
    File(File),
    Symbol(Symbol<'db>),
}

#[salsa::tracked(returns(deref))]
fn display_name<'db>(db: &'db dyn salsa::Database, source: Source<'db>) -> String {
    let name = match source {
        Source::File(file) => file.path(db),
        Source::Symbol(symbol) => symbol.name(db),
    };
    name.to_owned()
}
```

--------------------------------

### Storage::new

Source: https://docs.rs/salsa/latest/salsa/struct.Storage.html

Creates a new database storage with an optional event callback. The callback is invoked by the salsa runtime at various points during execution.

```APIDOC
## Storage::new

### Description
Creates a new database storage. The `event_callback` function is invoked by the salsa runtime at various points during execution.

### Method
`pub fn new(event_callback: Option<Box<dyn Fn(Event) + Send + Sync + 'static>>) -> Self`

### Parameters
- `event_callback` (Option<Box<dyn Fn(Event) + Send + Sync + 'static>>) - Optional callback invoked by the salsa runtime at various points during execution.

### Returns
- `Self` - A new `Storage<Db>` instance.

```

--------------------------------

### StorageHandle::new

Source: https://docs.rs/salsa/latest/salsa/struct.StorageHandle.html

Creates a new StorageHandle with an optional event callback. The callback is invoked with events of type Event and must be Send + Sync.

```APIDOC
## StorageHandle::new

### Description
Creates a new StorageHandle with an optional event callback. The callback is invoked with events of type Event and must be Send + Sync.

### Method
Constructor

### Signature
```rust
pub fn new(
    event_callback: Option<Box<dyn Fn(Event) + Send + Sync + 'static>>,
) -> Self
```

### Parameters
- **event_callback** (Option<Box<dyn Fn(Event) + Send + Sync + 'static>>) - Required - An optional callback function that receives events.

### Returns
- **Self** - A new StorageHandle instance.

```

--------------------------------

### Helper Function to Construct DatabaseKeyIndex

Source: https://docs.rs/salsa/latest/src/salsa/zalsa_local.rs.html

Creates a `DatabaseKeyIndex` from ingredient, index, and generation. Uses unsafe `Id::from_index` with a comment noting test inputs are valid `Id` indices, then applies generation and constructs the key.

```rust
fn key(ingredient: u32, index: u32, generation: u32) -> DatabaseKeyIndex {
    // SAFETY: Test inputs are valid `Id` indices.
    let id = unsafe { Id::from_index(index) }.with_generation(generation);

    DatabaseKeyIndex::new(IngredientIndex::new(ingredient), id)
}
```

--------------------------------

### StorageBuilder: Configure and build a Storage instance

Source: https://docs.rs/salsa/latest/src/salsa/storage.rs.html

Builder for a `Storage` instance, created via `Storage::builder`. Allows setting an event callback and manually registering ingredients when the `inventory` feature is disabled. The `build` method constructs the `Storage` with the provided options.

```rust
/// A builder for a [`Storage`] instance.
///
/// This type can be created with the [`Storage::builder`] function.
pub struct StorageBuilder<Db> {
    jars: Vec<ErasedJar>,
    event_callback: Option<Box<dyn Fn(crate::Event) + Send + Sync + 'static>>,
    _db: PhantomData<Db>,
}

impl<Db> Default for StorageBuilder<Db> {
    fn default() -> Self {
        Self {
            jars: Vec::new(),
            event_callback: None,
            _db: PhantomData,
        }
    }
}

impl<Db: Database> StorageBuilder<Db> {
    /// Set a callback for salsa events.
    ///
    /// The `event_callback` function will be invoked by the salsa runtime at various points during execution.
    pub fn event_callback(
        mut self,
        callback: Box<dyn Fn(crate::Event) + Send + Sync + 'static>,
    ) -> Self {
        self.event_callback = Some(callback);
        self
    }

    /// Manually register an ingredient.
    ///
    /// Manual ingredient registration is necessary when the `inventory` feature is disabled.
    pub fn ingredient<I: HasJar>(mut self) -> Self {
        self.jars.push(ErasedJar::erase::<I>());
        self
    }

    /// Construct the [`Storage`] using the provided builder options.
    pub fn build(self) -> Storage<Db> {
        Storage {
            handle: StorageHandle::with_jars(self.event_callback, self.jars),
            zalsa_local: ZalsaLocal::new(),
        }
    }
}
```

--------------------------------

### DatabaseImpl struct with Default, new, storage, and HasStorage implementations

Source: https://docs.rs/salsa/latest/src/salsa/database_impl.rs.html

Defines the default database implementation for salsa. The Default impl enables DEBUG-level tracing only when the detailed-trace feature is active and tracing is enabled; otherwise, no event handler is set. Provides new() as an alias for default, storage() accessor, and an unsafe HasStorage impl that returns references to the same storage field.

```rust
use tracing::Level;

use crate::storage::HasStorage;
use crate::{Database, Storage};

/// Default database implementation that you can use if you don't
/// require any custom user data.
#[derive(Clone)]
pub struct DatabaseImpl {
    storage: Storage<Self>,
}

impl Default for DatabaseImpl {
    fn default() -> Self {
        Self {
            // Default behavior: trace events at DEBUG when detailed tracing is enabled.
            storage: Storage::new(
                if cfg!(feature = "detailed-trace") && tracing::enabled!(Level::DEBUG) {
                    Some(Box::new(|event| {
                        crate::tracing::debug!("salsa_event({:?})", event)
                    }))
                } else {
                    None
                },
            ),
        }
    }
}

impl DatabaseImpl {
    /// Create a new database; equivalent to `Self::default`.
    pub fn new() -> Self {
        Self::default()
    }

    pub fn storage(&self) -> &Storage<Self> {
        &self.storage
    }
}

impl Database for DatabaseImpl {}

// SAFETY: The `storage` and `storage_mut` fields return a reference to the same storage field owned by `self`.
unsafe impl HasStorage for DatabaseImpl {
    #[inline(always)]
    fn storage(&self) -> &Storage<Self> {
        &self.storage
    }

    #[inline(always)]
    fn storage_mut(&mut self) -> &mut Storage<Self> {
        &mut self.storage
    }
}
```

--------------------------------

### Storage::builder

Source: https://docs.rs/salsa/latest/salsa/struct.Storage.html

Returns a builder for database storage, allowing configuration before construction.

```APIDOC
## Storage::builder

### Description
Returns a builder for database storage.

### Method
`pub fn builder() -> StorageBuilder<Db>`

### Returns
- `StorageBuilder<Db>` - A builder for database storage.

```

--------------------------------

### IngredientImpl::new: Create new interned ingredient

Source: https://docs.rs/salsa/latest/src/salsa/interned.rs.html

Constructs a new IngredientImpl with the given ingredient index, initializing shards and computing the shift value.

```rust
impl<C> IngredientImpl<C>
where
    C: Configuration,
{
    pub fn new(ingredient_index: IngredientIndex) -> Self {
        let shards = new_shards();
        let shift = usize::BITS - shards.len().trailing_zeros();

        Self {
```

--------------------------------

### DatabaseKeyIndex struct definition and methods

Source: https://docs.rs/salsa/latest/src/salsa/key.rs.html

Defines DatabaseKeyIndex with key_index and ingredient_index fields. Provides constructor, accessors, and internal methods for dependency verification and output tracking. Includes serde Serialize/Deserialize implementations under the 'persistence' feature and a Debug implementation that uses attached database context.

```rust
use std::fmt;

use crate::Id;
use crate::function::VerifyResult;
use crate::zalsa::{IngredientIndex, Zalsa};

// ANCHOR: DatabaseKeyIndex
/// An integer that uniquely identifies a particular query instance within the
/// database. Used to track input and output 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.
#[derive(Copy, Clone, PartialEq, Eq, Hash)]
pub struct DatabaseKeyIndex {
    key_index: Id,
    ingredient_index: IngredientIndex,
}
// ANCHOR_END: DatabaseKeyIndex

impl DatabaseKeyIndex {
    #[inline]
    pub(crate) const fn new(ingredient_index: IngredientIndex, key_index: Id) -> Self {
        Self {
            key_index,
            ingredient_index,
        }
    }

    pub const fn ingredient_index(self) -> IngredientIndex {
        self.ingredient_index
    }

    pub const fn key_index(self) -> Id {
        self.key_index
    }

    pub(crate) fn maybe_changed_after(
        &self,
        db: crate::database::RawDatabase<'_>,
        zalsa: &Zalsa,
        last_verified_at: crate::Revision,
    ) -> VerifyResult {
        // SAFETY: The `db` belongs to the ingredient
        unsafe {
            // here, `db` has to be either the correct type already, or a subtype (as far as trait
            // hierarchy is concerned)
            zalsa
                .lookup_ingredient(self.ingredient_index())
                .maybe_changed_after(zalsa, db, self.key_index(), last_verified_at)
        }
    }

    pub(crate) fn remove_stale_output(&self, zalsa: &Zalsa, executor: DatabaseKeyIndex) {
        zalsa
            .lookup_ingredient(self.ingredient_index())
            .remove_stale_output(zalsa, executor, self.key_index())
    }

    pub(crate) fn mark_validated_output(
        &self,
        zalsa: &Zalsa,
        database_key_index: DatabaseKeyIndex,
    ) {
        zalsa
            .lookup_ingredient(self.ingredient_index())
            .mark_validated_output(zalsa, database_key_index, self.key_index())
    }
}

#[cfg(feature = "persistence")]
impl serde::Serialize for DatabaseKeyIndex {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serde::Serialize::serialize(&(self.key_index, self.ingredient_index), serializer)
    }
}

#[cfg(feature = "persistence")]
impl<'de> serde::Deserialize<'de> for DatabaseKeyIndex {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let (key_index, ingredient_index) = serde::Deserialize::deserialize(deserializer)?;

        Ok(DatabaseKeyIndex {
            key_index,
            ingredient_index,
        })
    }
}

impl fmt::Debug for DatabaseKeyIndex {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        crate::attach::with_attached_database(|db| {
            let ingredient = db.zalsa().lookup_ingredient(self.ingredient_index());
            ingredient.fmt_index(self.key_index(), f)
        })
        .unwrap_or_else(|| {
            f.debug_tuple("DatabaseKeyIndex")
                .field(&self.ingredient_index())
                .field(&self.key_index())
                .finish()
        })
    }
}
```
Tokens:
Raw