EOP: Using a Dedicated Stable Option Type in Persistent State

rts/motoko-rts-tests/src/main.rs

@@ -8,6 +8,7 @@ mod gc;
 mod leb128;
 mod memory;
 mod principal_id;
+mod stable_option;
 mod text;
 mod utf8;
 
@@ -28,6 +29,7 @@ fn main() {
         gc::test();
         leb128::test();
         principal_id::test();
+        stable_option::test();
         text::test();
         utf8::test();
     }

rts/motoko-rts-tests/src/stable_option.rs

@@ -0,0 +1,24 @@
+use motoko_rts::stable_option::StableOption;
+
+pub fn test() {
+    println!("Testing StableOption ...");
+
+    let mut none: StableOption<usize> = StableOption::None;
+    assert!(none.is_none());
+    assert!(!none.is_some());
+    assert!(none.as_ref().is_none());
+    assert!(!none.as_ref().is_some());
+    assert!(none.as_mut().is_none());
+    assert!(!none.as_mut().is_some());
+
+    const TEST_VALUE: usize = 123456;
+    let mut some = Some(TEST_VALUE);
+    assert!(!some.is_none());
+    assert!(some.is_some());
+    assert_eq!(some.unwrap(), TEST_VALUE);
+    assert_eq!(some.as_ref().unwrap(), &TEST_VALUE);
+    assert_eq!(*some.as_mut().unwrap(), TEST_VALUE);
+
+    *some.as_mut().unwrap() = 0;
+    assert_eq!(some.unwrap(), 0);
+}

rts/motoko-rts/src/gc/incremental.rs

@@ -13,7 +13,7 @@
 
 use motoko_rts_macros::ic_mem_fn;
 
-use crate::{memory::Memory, types::*, visitor::visit_pointer_fields};
+use crate::{memory::Memory, stable_option::StableOption, types::*, visitor::visit_pointer_fields};
 
 use self::{
     partitioned_heap::{PartitionedHeap, PartitionedHeapIterator},
@@ -162,8 +162,8 @@ pub struct State {
     phase: Phase,
     partitioned_heap: PartitionedHeap,
     allocation_count: usize, // Number of allocations during an active GC run.
-    mark_state: Option<MarkState>,
-    iterator_state: Option<PartitionedHeapIterator>,
+    mark_state: StableOption<MarkState>,
+    iterator_state: StableOption<PartitionedHeapIterator>,
     statistics: Statistics,
 }
 
@@ -191,8 +191,8 @@ impl<'a, M: Memory + 'a> IncrementalGC<'a, M> {
             phase: Phase::Pause,
             partitioned_heap,
             allocation_count: 0,
-            mark_state: None,
-            iterator_state: None,
+            mark_state: StableOption::None,
+            iterator_state: StableOption::None,
             statistics,
         }
     }

rts/motoko-rts/src/gc/incremental/partitioned_heap.rs

@@ -45,6 +45,7 @@ use crate::{
     gc::incremental::mark_bitmap::BITMAP_ITERATION_END,
     memory::Memory,
     rts_trap_with,
+    stable_option::StableOption,
     types::*,
 };
 
@@ -231,15 +232,15 @@ impl Partition {
 #[repr(C)]
 pub struct PartitionedHeapIterator {
     partition_index: usize,
-    bitmap_iterator: Option<BitmapIterator>,
+    bitmap_iterator: StableOption<BitmapIterator>,
     visit_large_object: bool,
 }
 
 impl PartitionedHeapIterator {
     pub fn new(heap: &PartitionedHeap) -> PartitionedHeapIterator {
         let mut iterator = PartitionedHeapIterator {
             partition_index: 0,
-            bitmap_iterator: None,
+            bitmap_iterator: StableOption::None,
             visit_large_object: false,
         };
         iterator.skip_empty_partitions(heap);
@@ -286,15 +287,15 @@ impl PartitionedHeapIterator {
     fn start_object_iteration(&mut self, heap: &PartitionedHeap) {
         debug_assert!(self.partition_index <= MAX_PARTITIONS);
         if self.partition_index == MAX_PARTITIONS {
-            self.bitmap_iterator = None;
+            self.bitmap_iterator = StableOption::None;
             self.visit_large_object = false;
         } else {
             let partition = heap.get_partition(self.partition_index);
             if partition.has_large_content() {
-                self.bitmap_iterator = None;
+                self.bitmap_iterator = StableOption::None;
                 self.visit_large_object = partition.marked_size() > 0
             } else {
-                self.bitmap_iterator = Some(partition.get_bitmap().iterate());
+                self.bitmap_iterator = StableOption::Some(partition.get_bitmap().iterate());
                 self.visit_large_object = false;
             }
         }

rts/motoko-rts/src/gc/incremental/phases/evacuation_increment.rs

@@ -6,6 +6,7 @@ use crate::{
     },
     mem_utils::memcpy_words,
     memory::Memory,
+    stable_option::StableOption,
     types::*,
 };
 
@@ -20,13 +21,13 @@ impl<'a, M: Memory + 'a> EvacuationIncrement<'a, M> {
     pub unsafe fn start_phase(state: &mut State) {
         debug_assert!(state.iterator_state.is_none());
         let heap = &mut state.partitioned_heap;
-        state.iterator_state = Some(PartitionedHeapIterator::new(heap));
+        state.iterator_state = StableOption::Some(PartitionedHeapIterator::new(heap));
         heap.plan_evacuations();
     }
 
     pub unsafe fn complete_phase(state: &mut State) {
         debug_assert!(Self::evacuation_completed(state));
-        state.iterator_state = None;
+        state.iterator_state = StableOption::None;
     }
 
     pub unsafe fn evacuation_completed(state: &State) -> bool {

rts/motoko-rts/src/gc/incremental/phases/mark_increment.rs

@@ -8,6 +8,7 @@ use crate::{
         State,
     },
     memory::Memory,
+    stable_option::StableOption,
     types::*,
     visitor::visit_pointer_fields,
 };
@@ -32,15 +33,15 @@ impl<'a, M: Memory + 'a> MarkIncrement<'a, M> {
         state.partitioned_heap.start_collection(mem, time);
         debug_assert!(state.mark_state.is_none());
         let mark_stack = MarkStack::new(mem);
-        state.mark_state = Some(MarkState {
+        state.mark_state = StableOption::Some(MarkState {
             mark_stack,
             complete: false,
         });
     }
 
     pub unsafe fn complete_phase(state: &mut State) {
         debug_assert!(Self::mark_completed(state));
-        state.mark_state = None;
+        state.mark_state = StableOption::None;
     }
 
     pub unsafe fn mark_completed(state: &State) -> bool {

rts/motoko-rts/src/gc/incremental/phases/update_increment.rs

@@ -6,6 +6,7 @@ use crate::{
         time::BoundedTime,
         Roots, State,
     },
+    stable_option::StableOption,
     types::*,
     visitor::visit_pointer_fields,
 };
@@ -21,14 +22,14 @@ impl<'a> UpdateIncrement<'a> {
     pub unsafe fn start_phase(state: &mut State) {
         debug_assert!(state.iterator_state.is_none());
         let heap = &mut state.partitioned_heap;
-        state.iterator_state = Some(PartitionedHeapIterator::new(heap));
+        state.iterator_state = StableOption::Some(PartitionedHeapIterator::new(heap));
         heap.collect_large_objects();
         heap.plan_updates();
     }
 
     pub unsafe fn complete_phase(state: &mut State) {
         debug_assert!(Self::update_completed(state));
-        state.iterator_state = None;
+        state.iterator_state = StableOption::None;
         state.partitioned_heap.complete_collection();
     }
 

rts/motoko-rts/src/lib.rs

@@ -13,6 +13,8 @@ extern crate alloc;
 #[cfg(feature = "ic")]
 pub mod allocator;
 
+pub mod stable_option;
+
 #[macro_use]
 mod print;
 

rts/motoko-rts/src/stable_option.rs

@@ -0,0 +1,55 @@
+//! Option type with a fixed C-representation.
+//! This is used as a long-term option type in the persistent metata,
+//! such as the garbage collector state.
+//! As the native Rust type may change in future Rust releases,
+//! the Motoko runtime system uses its own dedicated `Option` type
+//! with a fixed long-term representation. This is used in the persistent
+//! metadata, such as in the garbage collector state.
+//! See:
+//! * `gc::incremental::State`
+//! * `gc::partitioned_heap::PartitionedHeapIterator`
+
+/// Stable option type used for orthogonal persistent state.
+/// Analogous use like the Rust-native `Option`.
+#[repr(C)]
+pub enum StableOption<T> {
+    None,
+    Some(T),
+}
+
+impl<T> StableOption<T> {
+    pub const fn is_none(&self) -> bool {
+        match self {
+            Self::None => true,
+            Self::Some(_) => false,
+        }
+    }
+
+    pub const fn is_some(&self) -> bool {
+        match self {
+            Self::None => false,
+            Self::Some(_) => true,
+        }
+    }
+
+    pub fn unwrap(self) -> T {
+        match self {
+            Self::None => panic!("Unwrapping `None` on `StableOption`"),
+            Self::Some(x) => x,
+        }
+    }
+
+    pub fn as_mut(&mut self) -> StableOption<&mut T> {
+        match *self {
+            Self::Some(ref mut x) => StableOption::Some(x),
+            Self::None => StableOption::None,
+        }
+    }
+
+    pub const fn as_ref(&self) -> StableOption<&T> {
+        match *self {
+            Self::Some(ref x) => StableOption::Some(x),
+            Self::None => StableOption::None,
+        }
+    }
+}