feat: Add PersistentHugr

Author: lmondada

hugr-core/Cargo.toml

@@ -57,6 +57,7 @@ thiserror = { workspace = true }
 typetag = { workspace = true }
 semver = { workspace = true, features = ["serde"] }
 zstd = { workspace = true, optional = true }
+relrc = "0.4.0"
 
 [dev-dependencies]
 rstest = { workspace = true }

hugr-core/src/hugr.rs

@@ -5,6 +5,7 @@ pub mod hugrmut;
 pub(crate) mod ident;
 pub mod internal;
 pub mod patch;
+pub mod persistent;
 pub mod serialize;
 pub mod validate;
 pub mod views;

hugr-core/src/hugr/persistent.rs

@@ -0,0 +1,207 @@
+//! Persistent data structure for Hugr mutations.
+//!
+//! This module provides a persistent data structure [`PersistentHugr`] that
+//! implements [`crate::HugrView`]; mutations to the data are stored as patches
+//! in an append-only context ([`PersistentContext`]) that can be shared among
+//! multiple [`PersistentHugr`]s. As a result, all versions of the data and
+//! references to them remain valid even as new patches are applied.
+//!
+//! The dependencies between the set of patches that define a [`PersistentHugr`]
+//! form a directed acyclic graph called [`PatchHistory`]. A [`PatchHistory`] is
+//! an induced subgraph of the [`PatchGraph`] that is guaranteed to only contain
+//! non-overlapping patches. By applying all patches in a [`PatchHistory`], we
+//! can materialize a [`Hugr`]. Traversing the materialised Hugr is equivalent
+//! to using the [`crate::HugrView`] implementation of the corresponding
+//! [`PersistentHugr`].
+//!
+//! ## Summary of data types
+//!
+//! - [`PersistentHugr`] A persistent data structure that implements
+//!   [`crate::HugrView`] and can be used as a drop-in replacement for a
+//!   [`crate::Hugr`] for read-only access and mutations through patches.
+//! - [`PersistentContext`] Stores all possible mutations (patches) applied to
+//!   [`PersistentHugr`] instances within a shared context. New
+//!   [`PersistentHugr`] can thus be created that combine patches from multiple
+//!   [`PersistentHugr`]s. It is a shared, reference-counted wrapper around a
+//!   [`PatchGraph`].
+//! - [`PatchGraph`] An directed acyclic graph of patches, recording the
+//!   dependencies between them. Includes the base Hugr and any number of
+//!   possibly incompatible (overlapping) patches.
+//! - [`PatchHistory`] A compatible subset of patches from a [`PatchGraph`] that
+//!   can be materialized into a [`Hugr`]. Guarantees that all included patches
+//!   have their dependencies satisfied and do not conflict. Any
+//!   [`PersistentHugr`] instance corresponds to a valid [`PatchHistory`].
+//!
+//! ## Usage
+//!
+//! A shared context can be created from a [`PatchGraph`]. Obtain a patch graph
+//! from a base hugr using [`PatchGraph::with_base`].
+//!
+//! A [`PersistentHugr`] can then be created with
+//! [`PersistentHugr::from_context_base`], or if you already have a set of patch
+//! IDs in the context, with [`PersistentHugr::try_from_patch_ids`]. Then add
+//! patches via [`PersistentHugr::add_replacement`], or apply them via
+//! patch traits.
+//!
+//! ## PersistentHugr as a "lens"
+//!
+//! A [`PersistentHugr`] is a view on a compatible subset of patches stored in a
+//! [`PersistentContext`]; the viewed data can also be modified by applying
+//! patches to it. This translates into adding patches to the context. In
+//! Haskell terminology, it is thus a "lens".
+
+mod patch_graph;
+mod resolver;
+mod trait_impls;
+
+use std::{
+    cell::{Ref, RefCell},
+    rc::Rc,
+};
+
+pub use patch_graph::{
+    IncompatibleHistory, InvalidPatch, PatchGraph, PatchHistory, PatchId, PatchNode,
+};
+pub use resolver::PointerEqResolver;
+
+use crate::{Hugr, SimpleReplacement};
+
+/// A replacement operation that can be applied to a [`PersistentHugr`].
+pub type PersistentReplacement = SimpleReplacement<PatchNode>;
+
+/// A shared mutable context for [`PersistentHugr`], so that all possible
+/// patches are stored in one place.
+///
+/// [`PersistentHugr`]s that share a context will be adding all patches to a
+/// common [`PatchGraph`].
+///
+/// Construct a [`PersistentContext`] from a [`PatchGraph`] with [`From::from`].
+///
+/// Mutations to [`PersistentContext`] only ever add new patches, so it is sound
+/// to share the same copy across multiple [`PersistentHugr`]: no data is ever
+/// deleted and so no NodeIds will ever be invalidated.
+#[derive(Clone)]
+pub struct PersistentContext(Rc<RefCell<PatchGraph>>);
+
+impl From<PatchGraph> for PersistentContext {
+    fn from(graph: PatchGraph) -> Self {
+        Self(Rc::new(RefCell::new(graph)))
+    }
+}
+
+impl PersistentContext {
+    /// Get a shared reference to the underlying [`PatchGraph`].
+    ///
+    /// ### Panics
+    /// This will panic if a mutable borrow to the context exists.
+    ///
+    /// Similarly, trying to mutably borrow whilst this reference exists, such
+    /// as adding patches to any [`PersistentHugr`] with this context, will
+    /// result in a panic.
+    pub fn patch_graph_ref(&self) -> Ref<PatchGraph> {
+        self.0.borrow()
+    }
+}
+
+/// A Hugr-like object that supports persistent mutation.
+///
+/// When mutations are applied to a [`PersistentHugr`], the object is mutated
+/// as expected but all references to previous versions of the object remain
+/// valid. Furthermore, older versions of the data can be recovered by
+/// traversing the object's history with [`Self::history`].
+///
+/// Multiple references to various versions of a Hugr can be maintained in
+/// parallel by sharing a single [`PersistentContext`] between them.
+///
+/// ## Supported mutation
+///
+/// [`PersistentHugr`] implements [`crate::HugrView`], so that it can used as
+/// a drop-in substitute for a Hugr wherever read-only access is required. It
+/// does not implement [`crate::hugr::HugrMut`], however. Mutations must be
+/// performed by applying patches (see [`crate::hugr::patch::VerifyPatch`] and
+/// [`crate::hugr::patch::ApplyPatch`]). Currently, only [`SimpleReplacement`]
+/// patches are supported. You can use [`Self::add_replacement`] to add a patch
+/// to `self`, or use the aforementioned patch traits.
+///
+/// ## Patches and history
+///
+/// A [`PersistentHugr`] is composed of a unique base Hug, along with a set of
+/// all mutations applied to it. All mutations are stored in the form of patches
+/// that apply on top of the base Hugr. You may think of it as a "queue" of
+/// patches: whenever a patch is "applied", it is in reality just added to the
+/// queue. In practice, the total order of the queue is irrelevant, as patches
+/// only depend on a subset of the previously applied patches. This creates a
+/// partial order on the patches---a directed acyclic graph that we call the
+/// patch history. Multiple [`PersistentHugr`] that share a common context then
+/// share a subset of that history.
+///
+/// The history of all patches applied and their dependencies is stored in a
+/// [`PatchHistory`] that can be retrieved with [`Self::history`].
+pub struct PersistentHugr {
+    /// The context to which all patches are added.
+    context: PersistentContext,
+    /// The subset of patches stored in context that defines the Hugr.
+    ///
+    /// This consists only of compatible patches, so that all patches can be
+    /// applied. The resulting Hugr can be extracted with [`Self::to_hugr`].
+    history: PatchHistory,
+}
+
+impl PersistentHugr {
+    /// Create a [`PersistentHugr`] corresponding to the base Hugr of the
+    /// given context.
+    pub fn from_context_base(context: PersistentContext) -> Self {
+        let history = context.patch_graph_ref().base_history();
+        Self { context, history }
+    }
+
+    /// Create a [`PersistentHugr`] from a list of patch ids.
+    ///
+    /// `Self` will correspond to the Hugr obtained by applying the history
+    /// of all patches with the given IDs (and their ancestors).
+    ///
+    /// `patch_ids` must be patches in `context`.
+    ///
+    /// If the history of the patch ids would include two patches which are
+    /// incompatible, an error is returned.
+    pub fn try_from_patch_ids(
+        patch_ids: impl IntoIterator<Item = PatchId>,
+        context: PersistentContext,
+    ) -> Result<Self, IncompatibleHistory> {
+        let history = context.patch_graph_ref().try_get_history(patch_ids)?;
+        Ok(Self { context, history })
+    }
+
+    /// Convert this `PersistentHugr` to a materialized Hugr by applying all
+    /// patches in the current history.
+    ///
+    /// This operation may be expensive and should be avoided in
+    /// performance-critical paths. For read-only views into the data, rely
+    /// instead on the [`crate::HugrView`] implementation when possible.
+    pub fn to_hugr(&self) -> Hugr {
+        self.history.to_hugr(&self.context.patch_graph_ref())
+    }
+
+    /// The history of all patches in `self`.
+    pub fn history(&self) -> &PatchHistory {
+        &self.history
+    }
+
+    /// Add a patch to `self`.
+    ///
+    /// Currently, patches must be [`SimpleReplacement`]s.
+    pub fn add_replacement(&mut self, replacement: PersistentReplacement) {
+        let mut patch_graph = self.context.0.borrow_mut();
+        let patch_id = patch_graph.add_replacement(replacement);
+        self.history
+            .try_add_patch(patch_id, &patch_graph)
+            .expect("invalid nodes in replacement")
+    }
+
+    /// Iterator over the patch IDs in the history.
+    ///
+    /// The patches are not guaranteed to be in any particular order.
+    pub fn patch_ids(&self) -> impl Iterator<Item = PatchId> + '_ {
+        self.history.patch_ids()
+    }
+}