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}