mago_database/
change.rs

1use std::borrow::Cow;
2use std::sync::Arc;
3use std::sync::Mutex;
4
5use crate::error::DatabaseError;
6use crate::file::File;
7use crate::file::FileId;
8
9/// Represents a single, deferred database operation.
10///
11/// An instruction to be applied to a `Database` as part of a [`ChangeLog`].
12#[derive(Debug)]
13pub enum Change {
14    /// An instruction to add a new file.
15    Add(File),
16    /// An instruction to update an existing file, identified by its `FileId`.
17    Update(FileId, Cow<'static, str>),
18    /// An instruction to delete an existing file, identified by its `FileId`.
19    Delete(FileId),
20}
21
22/// A thread-safe, cloneable transaction log for collecting database operations.
23///
24/// This struct acts as a "Unit of Work," allowing multiple threads to concurrently
25/// record operations without directly mutating the `Database`. The collected changes
26/// can then be applied later in a single batch operation. This pattern avoids lock
27/// contention on the main database during processing.
28#[derive(Clone, Debug)]
29pub struct ChangeLog {
30    pub(crate) changes: Arc<Mutex<Vec<Change>>>,
31}
32
33impl Default for ChangeLog {
34    fn default() -> Self {
35        Self::new()
36    }
37}
38
39impl ChangeLog {
40    /// Creates a new, empty `ChangeLog`.
41    #[must_use]
42    pub fn new() -> Self {
43        Self { changes: Arc::new(Mutex::new(Vec::new())) }
44    }
45
46    /// Records a request to add a new file.
47    ///
48    /// # Errors
49    ///
50    /// Returns a `DatabaseError::PoisonedLogMutex` if another thread panicked
51    /// while holding the lock, leaving the change log in an unusable state.
52    pub fn add(&self, file: File) -> Result<(), DatabaseError> {
53        self.changes.lock().map_err(|_| DatabaseError::PoisonedLogMutex)?.push(Change::Add(file));
54        Ok(())
55    }
56
57    /// Records a request to update an existing file's content by its `FileId`.
58    ///
59    /// # Errors
60    ///
61    /// Returns a `DatabaseError::PoisonedLogMutex` if another thread panicked
62    /// while holding the lock, leaving the change log in an unusable state.
63    pub fn update(&self, id: FileId, new_contents: Cow<'static, str>) -> Result<(), DatabaseError> {
64        self.changes.lock().map_err(|_| DatabaseError::PoisonedLogMutex)?.push(Change::Update(id, new_contents));
65        Ok(())
66    }
67
68    /// Records a request to delete a file by its `FileId`.
69    ///
70    /// # Errors
71    ///
72    /// Returns a `DatabaseError::PoisonedLogMutex` if another thread panicked
73    /// while holding the lock, leaving the change log in an unusable state.
74    pub fn delete(&self, id: FileId) -> Result<(), DatabaseError> {
75        self.changes.lock().map_err(|_| DatabaseError::PoisonedLogMutex)?.push(Change::Delete(id));
76        Ok(())
77    }
78
79    /// Returns a vector of all `FileId`s affected by the recorded changes.
80    ///
81    /// This includes IDs for files being added, updated, or deleted.
82    ///
83    /// # Errors
84    ///
85    /// - `DatabaseError::PoisonedLogMutex`: Returned if the internal lock was poisoned
86    pub fn changed_file_ids(&self) -> Result<Vec<FileId>, DatabaseError> {
87        let changes = self.changes.lock().map_err(|_| DatabaseError::PoisonedLogMutex)?;
88        let mut ids = Vec::new();
89        for change in &*changes {
90            match change {
91                Change::Add(file) => ids.push(file.id),
92                Change::Update(id, _) => ids.push(*id),
93                Change::Delete(id) => ids.push(*id),
94            }
95        }
96
97        Ok(ids)
98    }
99
100    /// Consumes the change log and returns the vector of collected changes.
101    ///
102    /// This operation safely unwraps the underlying list of changes. It will
103    /// only succeed if called on the last remaining reference to the change log,
104    /// which guarantees that no other threads can be modifying the list.
105    ///
106    /// # Errors
107    ///
108    /// - `DatabaseError::ChangeLogInUse`: Returned if other `Arc` references to this change log still exist.
109    /// - `DatabaseError::PoisonedLogMutex`: Returned if the internal lock was poisoned because another thread panicked while holding it.
110    pub fn into_inner(self) -> Result<Vec<Change>, DatabaseError> {
111        match Arc::try_unwrap(self.changes) {
112            Ok(mutex) => mutex.into_inner().map_err(|_| DatabaseError::PoisonedLogMutex),
113            Err(_) => Err(DatabaseError::ChangeLogInUse),
114        }
115    }
116}
mago_database/change.rs

mago_database/
change.rs
