ModifyingPieces: Provide on-your-own-head constructors, and doc

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/src/global.rs b/src/global.rs
index 487d79a72aa174d1012d2dd554b8f0d7834355e2..2feb7cb215cf092b05648dfd75f939ee859b421f 100644 (file)
--- a/src/global.rs
+++ b/src/global.rs
@@ -89,6 +89,10 @@ deref_to_field!{IPiece, IPieceTraitObj, p}
 #[serde(transparent)]
 pub struct IPieces(ActualIPieces);
 pub type ActualIPieces = SecondarySlotMap<PieceId, IPiece>;
+
+/// Proof token that it is OK to modify the array
+///
+/// This exists to prevent bugs where we forget to save aux
 #[derive(Copy,Clone,Debug)]
 pub struct ModifyingPieces(());
 
@@ -282,6 +286,12 @@ impl Debug for Instance {
   }
 }
 
+impl ModifyingPieces {
+  pub fn allow_without_necessarily_saving() -> ModifyingPieces {
+    ModifyingPieces(())
+  }
+}
+
 // ---------- Main API for instance lifecycle ----------
 
 impl InstanceRef {
@@ -970,6 +980,12 @@ impl<'ig> InstanceGuard<'ig> {
     ModifyingPieces(())
   }
 
+  pub fn modify_pieces_not_necessarily_saving_aux(&mut self)
+                                                  -> ModifyingPieces {
+    self.save_game_later();
+    ModifyingPieces(())
+  }
+
   fn token_register<Id:AccessId>(
     &mut self,
     token: RawToken,