feat(air): introduce explicit types for generation numbers (#530)

---------

Co-authored-by: vms <michail.vms@gmail.com>
Co-authored-by: Anatolios Laskaris <github_me@nahsi.dev>

crates/air-lib/interpreter-data/src/executed_state.rs

@@ -17,6 +17,7 @@
 mod impls;
 mod se_de;
 
+use crate::GenerationIdx;
 use crate::JValue;
 use crate::TracePos;
 
@@ -86,7 +87,7 @@ pub enum ValueRef {
     /// The call value is stored to a stream variable.
     Stream {
         cid: Rc<CID<ServiceResultAggregate>>,
-        generation: u32,
+        generation: GenerationIdx,
     },
     /// The call value is not stored.
     Unused(Rc<CID<JValue>>),
@@ -128,7 +129,7 @@ pub struct ServiceResultAggregate {
 ///     (call 3)
 ///     (call 4)
 /// )
-///
+///x
 /// Having started with stream with two elements {v1, v2} the resulted trace would looks like
 /// [(1) (2)] [(1) (2)] [(3) (4)] [(3) (4)]  <---  the sequence of call states
 ///    v1        v2        v2        v1      <---- corresponding values from $stream that
@@ -179,7 +180,7 @@ pub struct FoldResult {
 #[serde(rename_all = "snake_case")]
 pub struct ApResult {
     #[serde(rename = "gens")]
-    pub res_generations: Vec<u32>,
+    pub res_generations: Vec<GenerationIdx>,
 }
 
 /// Contains ids of element that were on a stream at the moment of an appropriate canon call.

crates/air-lib/interpreter-data/src/executed_state/impls.rs

@@ -48,13 +48,11 @@ impl CallResult {
     }
 
     pub fn executed_stream(
-        service_result_agg_cid: Rc<CID<ServiceResultAggregate>>,
-        generation: u32,
+        cid: Rc<CID<ServiceResultAggregate>>,
+        generation: GenerationIdx,
     ) -> CallResult {
-        Self::executed_service_result(ValueRef::Stream {
-            cid: service_result_agg_cid,
-            generation,
-        })
+        let value = ValueRef::Stream { cid, generation };
+        CallResult::Executed(value)
     }
 
     pub fn executed_unused(value_cid: Rc<CID<JValue>>) -> CallResult {
@@ -87,7 +85,7 @@ impl ExecutedState {
 }
 
 impl ApResult {
-    pub fn new(res_generation: u32) -> Self {
+    pub fn new(res_generation: GenerationIdx) -> Self {
         Self {
             res_generations: vec![res_generation],
         }

crates/air-lib/interpreter-data/src/generation_idx.rs

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2023 Fluence Labs Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+use serde::Deserialize;
+use serde::Serialize;
+
+use std::cmp::Ordering;
+use std::fmt::Debug;
+use std::fmt::Display;
+
+type GenerationIdxType = u32;
+
+#[derive(Copy, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(transparent)]
+#[repr(transparent)]
+pub struct GenerationIdx(GenerationIdxType);
+
+impl GenerationIdx {
+    pub fn checked_add(self, other: Self) -> Option<Self> {
+        self.0.checked_add(other.0).map(Self)
+    }
+
+    pub fn checked_sub(self, other: Self) -> Option<Self> {
+        self.0.checked_sub(other.0).map(Self)
+    }
+
+    pub fn next(self) -> Self {
+        // TODO: check for overflow
+        Self::from(self.0 as usize + 1)
+    }
+
+    pub fn prev(self) -> Self {
+        // TODO: check for overflow
+        Self::from(self.0 as usize - 1)
+    }
+}
+
+impl PartialOrd<usize> for GenerationIdx {
+    fn partial_cmp(&self, other: &usize) -> Option<Ordering> {
+        let self_as_usize: usize = (*self).into();
+        self_as_usize.partial_cmp(other)
+    }
+}
+
+impl PartialEq<usize> for GenerationIdx {
+    fn eq(&self, other: &usize) -> bool {
+        let self_as_usize: usize = (*self).into();
+        self_as_usize == *other
+    }
+}
+
+//TODO: replace these two traits with try-* versions
+impl From<usize> for GenerationIdx {
+    fn from(value: usize) -> Self {
+        GenerationIdx(value as u32)
+    }
+}
+
+impl From<GenerationIdx> for usize {
+    fn from(value: GenerationIdx) -> Self {
+        value.0 as usize
+    }
+}
+
+impl Debug for GenerationIdx {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        Debug::fmt(&self.0, f)
+    }
+}
+
+impl Display for GenerationIdx {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        Display::fmt(&self.0, f)
+    }
+}

crates/air-lib/interpreter-data/src/lib.rs

@@ -28,6 +28,7 @@
 
 mod cid_store;
 mod executed_state;
+mod generation_idx;
 mod interpreter_data;
 mod stream_generations;
 mod trace;
@@ -35,6 +36,7 @@ mod trace_pos;
 
 pub use cid_store::*;
 pub use executed_state::*;
+pub use generation_idx::*;
 pub use interpreter_data::*;
 pub use stream_generations::*;
 pub use trace::*;

crates/air-lib/interpreter-data/src/stream_generations.rs

@@ -14,13 +14,14 @@
  * limitations under the License.
  */
 
+use crate::GenerationIdx;
 use air_parser::AirPos;
 
 use std::collections::HashMap;
 
 /// Mapping from a stream name to it's generation count.
 /// Similar to pi-calculus non-restricted names/channels.
-pub type GlobalStreamGens = HashMap<String, u32>;
+pub type GlobalStreamGens = HashMap<String, GenerationIdx>;
 
 /// Mapping from a stream name to
 ///    position of a new instruction in a script that creates a scope for a stream
@@ -30,4 +31,4 @@ pub type GlobalStreamGens = HashMap<String, u32>;
 /// so it could be met several times during script execution. This field anchors iteration
 /// where it was met.
 /// Similar to pi-calculus restricted names/channels.
-pub type RestrictedStreamGens = HashMap<String, HashMap<AirPos, Vec<u32>>>;
+pub type RestrictedStreamGens = HashMap<String, HashMap<AirPos, Vec<GenerationIdx>>>;