From ac567240ea82c122314108a9d232dd7bb99a88a9 Mon Sep 17 00:00:00 2001 From: Stuart Axelbrooke Date: Sun, 12 Oct 2025 13:44:25 -0700 Subject: [PATCH] Add design notes for build state --- databuild/build_state.rs | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/databuild/build_state.rs b/databuild/build_state.rs index 447933d..16c7516 100644 --- a/databuild/build_state.rs +++ b/databuild/build_state.rs @@ -7,6 +7,27 @@ use serde::{Deserialize, Serialize}; use std::collections::BTreeMap; use std::error::Error; +/** +Design Notes + +The build state struct is the heart of the service and orchestrator, adapting build events to +higher level questions about build state. One temptation is to implement the build state as a set +of hierarchically defined reducers, to achieve information hiding and factor system capabilities and +state tracking simply. Unfortunately, to update state based on an event, you need a mutable borrow +of some part of the build state (that the reducer controls, for instance), and an immutable borrow +of the whole state for read/query purposes. The whole state needs to be available to handle state +updates like "this is the list of currently active job runs" in response to a job run event. Put +simply, this isn't possible without introducing some locking of the whole state and mutable state +subset, since they would conflict (the mutable subset would have already been borrowed, so can't +be borrowed immutably as part of the whole state borrow). You might also define a "query" phase +in which reducers query the state based on the received event, but that just increases complexity. + +Instead, databuild opts for an entity-component system (ECS) that just provides the whole build +state mutably to all state update functionality, trusting that we know how to use it responsibly. +This means no boxing or "query phase", and means we can have all state updates happen as map lookups +and updates, which is exceptionally fast. +*/ + #[derive(Debug)] pub struct BuildState { wants: BTreeMap,