- add doc comments to generation traits and functions

- remove pick_index from places where it's possible to use pick instead
- allow multiple values to be inserted in the insert-select property

Author: alpaylan

simulator/generation/mod.rs

@@ -8,14 +8,30 @@ pub mod property;
 pub mod query;
 pub mod table;
 
+/// Arbitrary trait for generating random values
+/// An implementation of arbitrary is assumed to be a uniform sampling of
+/// the possible values of the type, with a bias towards smaller values for
+/// practicality.
 pub trait Arbitrary {
     fn arbitrary<R: Rng>(rng: &mut R) -> Self;
 }
 
+/// ArbitraryFrom trait for generating random values from a given value
+/// ArbitraryFrom allows for constructing relations, where the generated
+/// value is dependent on the given value. These relations could be constraints
+/// such as generating an integer within an interval, or a value that fits in a table,
+/// or a predicate satisfying a given table row.
 pub trait ArbitraryFrom<T> {
     fn arbitrary_from<R: Rng>(rng: &mut R, t: T) -> Self;
 }
 
+/// Frequency is a helper function for composing different generators with different frequency
+/// of occurences.
+/// The type signature for the `N` parameter is a bit complex, but it
+/// roughly corresponds to a type that can be summed, compared, subtracted and sampled, which are
+/// the operations we require for the implementation.
+// todo: switch to a simpler type signature that can accomodate all integer and float types, which
+//       should be enough for our purposes.
 pub(crate) fn frequency<
     'a,
     T,
@@ -38,6 +54,7 @@ pub(crate) fn frequency<
     unreachable!()
 }
 
+/// one_of is a helper function for composing different generators with equal probability of occurence.
 pub(crate) fn one_of<'a, T, R: rand::Rng>(
     choices: Vec<Box<dyn Fn(&mut R) -> T + 'a>>,
     rng: &mut R,
@@ -46,15 +63,20 @@ pub(crate) fn one_of<'a, T, R: rand::Rng>(
     choices[index](rng)
 }
 
+/// pick is a helper function for uniformly picking a random element from a slice
 pub(crate) fn pick<'a, T, R: rand::Rng>(choices: &'a [T], rng: &mut R) -> &'a T {
     let index = rng.gen_range(0..choices.len());
     &choices[index]
 }
 
+/// pick_index is typically used for picking an index from a slice to later refer to the element
+/// at that index.
 pub(crate) fn pick_index<R: rand::Rng>(choices: usize, rng: &mut R) -> usize {
     rng.gen_range(0..choices)
 }
 
+/// gen_random_text uses `anarchist_readable_name_generator_lib` to generate random
+/// readable names for tables, columns, text values etc.
 fn gen_random_text<T: Rng>(rng: &mut T) -> String {
     let big_text = rng.gen_ratio(1, 1000);
     if big_text {

simulator/generation/property.rs

@@ -7,7 +7,7 @@ use crate::{
 };
 
 use super::{
-    frequency, pick, pick_index,
+    frequency, pick,
     plan::{Assertion, Interaction, InteractionStats, ResultSet},
     ArbitraryFrom,
 };
@@ -66,20 +66,26 @@ impl Property {
             Property::DoubleCreateFailure { .. } => "Double-Create-Failure".to_string(),
         }
     }
+    /// interactions construct a list of interactions, which is an executable representation of the property.
+    /// the requirement of property -> vec<interaction> conversion emerges from the need to serialize the property,
+    /// and `interaction` cannot be serialized directly.
     pub(crate) fn interactions(&self) -> Vec<Interaction> {
         match self {
             Property::InsertSelect {
                 insert,
                 queries,
                 select,
             } => {
-                // Check that the row is there
-                let row = insert
-                    .values
-                    .first() // `.first` is safe, because we know we are inserting a row in the insert select property
-                    .expect("insert query should have at least 1 value")
-                    .clone();
+                // Check that the insert query has at least 1 value
+                assert!(
+                    !insert.values.is_empty(),
+                    "insert query should have at least 1 value"
+                );
 
+                // Pick a random row within the insert values
+                let row = pick(&insert.values, &mut rand::thread_rng()).clone();
+
+                // Assume that the table exists
                 let assumption = Interaction::Assumption(Assertion {
                     message: format!("table {} exists", insert.table),
                     func: Box::new({
@@ -190,26 +196,18 @@ fn property_insert_select<R: rand::Rng>(
 ) -> Property {
     // Get a random table
     let table = pick(&env.tables, rng);
-    // Pick a random column
-    let column_index = pick_index(table.columns.len(), rng);
-    let column = &table.columns[column_index].clone();
-    // Generate a random value of the column type
-    let value = Value::arbitrary_from(rng, &column.column_type);
-    // Create a whole new row
-    let mut row = Vec::new();
-    for (i, column) in table.columns.iter().enumerate() {
-        if i == column_index {
-            row.push(value.clone());
-        } else {
-            let value = Value::arbitrary_from(rng, &column.column_type);
-            row.push(value);
-        }
-    }
+    // Generate rows to insert
+    let rows = (0..rng.gen_range(1..=5))
+        .map(|_| Vec::<Value>::arbitrary_from(rng, table))
+        .collect::<Vec<_>>();
+
+    // Pick a random row to select
+    let row = pick(&rows, rng).clone();
 
-    // Insert the row
+    // Insert the rows
     let insert_query = Insert {
         table: table.name.clone(),
-        values: vec![row.clone()],
+        values: rows,
     };
 
     // Create random queries respecting the constraints

simulator/generation/table.rs

@@ -1,8 +1,6 @@
 use rand::Rng;
 
-use crate::generation::{
-    gen_random_text, pick, pick_index, readable_name_custom, Arbitrary, ArbitraryFrom,
-};
+use crate::generation::{gen_random_text, pick, readable_name_custom, Arbitrary, ArbitraryFrom};
 use crate::model::table::{Column, ColumnType, Name, Table, Value};
 
 impl Arbitrary for Name {
@@ -45,6 +43,17 @@ impl Arbitrary for ColumnType {
     }
 }
 
+impl ArbitraryFrom<&Table> for Vec<Value> {
+    fn arbitrary_from<R: rand::Rng>(rng: &mut R, table: &Table) -> Self {
+        let mut row = Vec::new();
+        for column in table.columns.iter() {
+            let value = Value::arbitrary_from(rng, &column.column_type);
+            row.push(value);
+        }
+        row
+    }
+}
+
 impl ArbitraryFrom<&Vec<&Value>> for Value {
     fn arbitrary_from<R: Rng>(rng: &mut R, values: &Vec<&Self>) -> Self {
         if values.is_empty() {
@@ -74,8 +83,8 @@ impl ArbitraryFrom<&Vec<&Value>> for LTValue {
             return Self(Value::Null);
         }
 
-        let index = pick_index(values.len(), rng);
-        Self::arbitrary_from(rng, values[index])
+        let value = pick(values, rng);
+        Self::arbitrary_from(rng, *value)
     }
 }
 
@@ -134,8 +143,8 @@ impl ArbitraryFrom<&Vec<&Value>> for GTValue {
             return Self(Value::Null);
         }
 
-        let index = pick_index(values.len(), rng);
-        Self::arbitrary_from(rng, values[index])
+        let value = pick(values, rng);
+        Self::arbitrary_from(rng, *value)
     }
 }