Skip to main content

vvv_engine/
command.rs

1//! An engine runs commands. A [`Command`] is a request as data — an intent,
2//! a question — that knows how to answer itself against the tree; the
3//! engine's part is the plumbing: bring the graph up to date, hand it over,
4//! and for a mutation bind the answer to a plan. Nothing about a command
5//! lives on the engine.
6
7use std::sync::MutexGuard;
8
9use crate::graph::Graph;
10use crate::{Engine, EngineError, Retention, Workspace};
11
12/// One request and its answer. Implemented by the protocol's intents and
13/// queries, each in the module that holds its components.
14pub trait Command {
15    type Output;
16
17    /// Answer against the tree the context holds. A mutation answers with a
18    /// [`Planned`](crate::Planned) result; nothing is written here.
19    fn run(self, cx: &mut Context<'_>) -> Result<Self::Output, EngineError>;
20}
21
22/// What a command runs against: the graph, brought up to date, and the
23/// workspace it was built from.
24pub struct Context<'a> {
25    pub(crate) graph: MutexGuard<'a, Graph>,
26    pub(crate) workspace: &'a Workspace,
27    engine: &'a Engine,
28}
29
30impl<'a> Context<'a> {
31    pub(crate) fn new(engine: &'a Engine, graph: MutexGuard<'a, Graph>) -> Self {
32        Self {
33            graph,
34            workspace: engine.workspace(),
35            engine,
36        }
37    }
38
39    /// An engine over a staging copy of the workspace — an overlay the real
40    /// files never see — reading it afresh: how a batch plans each step
41    /// against the state the previous one leaves.
42    pub(crate) fn staged(&self) -> (Engine, Workspace) {
43        let staging = self.workspace.staged();
44        let engine = Engine::new(staging.clone(), self.engine.languages().clone())
45            .with_retention(Retention::PerCall);
46        (engine, staging)
47    }
48}