documentation, borrow_check

Author: frankmcsherry

src/bin/borrow_check.rs

@@ -0,0 +1,119 @@
+extern crate datalog;
+use datalog::Iteration;
+
+type Region = u32;
+type Borrow = u32;
+type Point = u32;
+
+fn main() {
+
+    let subset = {
+
+        // Create a new iteration context, ...
+        let mut iteration1 = Iteration::new();
+
+        // .. some variables, ..
+        let subset = iteration1.variable::<(Region, Region, Point)>("subset");
+
+        // different indices for `subset`.
+        let subset_r1p = iteration1.variable::<((Region, Point), Region)>("subset_r1p");
+        let subset_r2p = iteration1.variable::<((Region, Point), Region)>("subset_r2p");
+        let subset_p = iteration1.variable::<(Point, (Region, Region))>("subset_p");
+
+        let subset_1 = iteration1.variable::<((Region, Point), Region)>("subset_1");
+        let subset_2 = iteration1.variable::<((Region, Point), Region)>("subset_2");
+
+        let region_live_at = iteration1.variable::<((Region, Point), ())>("region_live_at");
+        let cfg_edge_p = iteration1.variable::<(Point, Point)>("cfg_edge_p");
+
+        // load initial facts.
+        subset.insert(Vec::new().into());
+        region_live_at.insert(Vec::new().into());
+        cfg_edge_p.insert(Vec::new().into());
+
+        // .. and then start iterating rules!
+        while iteration1.changed() {
+
+            // remap fields to re-index by keys.
+            subset_r1p.from_map(&subset, |&(r1,r2,p)| ((r1,p),r2));
+            subset_r2p.from_map(&subset, |&(r1,r2,p)| ((r2,p),r1));
+            subset_p.from_map(&subset, |&(r1,r2,p)| (p,(r1,r2)));
+
+            // R0: subset(R1, R2, P) :- outlives(R1, R2, P).
+            // Already loaded; outlives is static.
+
+            // R1: subset(R1, R3, P) :-
+            //   subset(R1, R2, P),
+            //   subset(R2, R3, P).
+            subset.from_join(&subset_r2p, &subset_r1p, |&(_r2,p),&r1,&r3| (r1,r3,p));
+
+            // R2: subset(R1, R2, Q) :-
+            //   subset(R1, R2, P),
+            //   cfg_edge(P, Q),
+            //   region_live_at(R1, Q),
+            //   region_live_at(R2, Q).
+
+            subset_1.from_join(&subset_p, &cfg_edge_p, |&_p, &(r1,r2), &q| ((r1,q),r2));
+            subset_2.from_join(&subset_1, &region_live_at, |&(r1,q),&r2,&()| ((r2,q),r1));
+            subset.from_join(&subset_2, &region_live_at, |&(r2,q),&r1,&()| (r1,r2,q));
+
+        }
+
+        subset_r1p.complete()
+    };
+
+    let requires = {
+
+        // Create a new iteration context, ...
+        let mut iteration2 = Iteration::new();
+
+        // .. some variables, ..
+        let requires = iteration2.variable::<(Region, Borrow, Point)>("requires");
+        requires.insert(Vec::new().into());
+
+        let requires_rp = iteration2.variable::<((Region, Point), Borrow)>("requires_rp");
+        let requires_bp = iteration2.variable::<((Borrow, Point), Region)>("requires_bp");
+
+        let requires_1 = iteration2.variable::<(Point, (Borrow, Region))>("requires_1");
+        let requires_2 = iteration2.variable::<((Region, Point), Borrow)>("requires_2");
+
+        let subset_r1p = iteration2.variable::<((Region, Point), Region)>("subset_r1p");
+        subset_r1p.insert(subset);
+
+        let killed = Vec::new().into();
+        let region_live_at = iteration2.variable::<((Region, Point), ())>("region_live_at");
+        let cfg_edge_p = iteration2.variable::<(Point, Point)>("cfg_edge_p");
+
+        // .. and then start iterating rules!
+        while iteration2.changed() {
+
+            requires_rp.from_map(&requires, |&(r,b,p)| ((r,p),b));
+            requires_bp.from_map(&requires, |&(r,b,p)| ((b,p),r));
+
+            // requires(R, B, P) :- borrow_region(R, B, P).
+            // Already loaded; borrow_region is static.
+
+            // requires(R2, B, P) :-
+            //   requires(R1, B, P),
+            //   subset(R1, R2, P).
+            requires.from_join(&requires_rp, &subset_r1p, |&(_r1, p), &b, &r2| (r2, b, p));
+
+            // requires(R, B, Q) :-
+            //   requires(R, B, P),
+            //   !killed(B, P),
+            //   cfg_edge(P, Q),
+            //   (region_live_at(R, Q); universal_region(R)).
+
+            requires_1.from_antijoin(&requires_bp, &killed, |&(b,p),&r| (p,(b,r)));
+            requires_2.from_join(&requires_1, &cfg_edge_p, |&_p, &(b,r), &q| ((r,q),b));
+            requires.from_join(&requires_2, &region_live_at, |&(r,q),&b,&()| (r,b,q));
+        }
+
+        requires.complete()
+    };
+
+        // borrow_live_at(B, P) :- requires(R, B, P), region_live_at(R, P)
+
+        // borrow_live_at(B, P) :- requires(R, B, P), universal_region(R).
+
+}

src/join.rs

@@ -1,3 +1,5 @@
+//! Join functionality.
+
 use super::{Variable, Relation};
 
 pub fn join_into<Key: Ord, Val1: Ord, Val2: Ord, Result: Ord, F: Fn(&Key, &Val1, &Val2)->Result>(
@@ -28,6 +30,7 @@ pub fn join_into<Key: Ord, Val1: Ord, Val2: Ord, Result: Ord, F: Fn(&Key, &Val1,
     output.insert(results.into());
 }
 
+/// Moves all recent tuples from `input1` that are not present in `input2` into `output`.
 pub fn antijoin_into<Key: Ord, Val: Ord, Result: Ord, F: Fn(&Key, &Val)->Result>(
     input1: &Variable<(Key, Val)>,
     input2: &Relation<Key>,

src/lib.rs

@@ -1,10 +1,15 @@
-//! A lightweight Datalog executor in Rust
+//! A lightweight Datalog engine in Rust
 //!
-//! The intended design is that there are static relations, perhaps described
-//! by sorted `Vec<(Key, Val)>` lists, at which point you can make an iterative
-//! context in which you can name variables, define computations, and bind the
-//! results to named variables.
+//! The intended design is that one has static `Relation` types that are sets
+//! of tuples, and `Variable` types that represent monotonically increasing
+//! sets of tuples.
 //!
+//! The types are mostly wrappers around `Vec<Tuple>` indicating sorted-ness,
+//! and the intent is that this code can be dropped in the middle of an otherwise
+//! normal Rust program, run to completion, and then the results extracted as
+//! vectors again.
+
+#![forbid(missing_docs)]
 
 use std::rc::Rc;
 use std::cell::RefCell;
@@ -18,6 +23,10 @@ mod join;
 /// Datalog computation we want to be sure that certain relations are not able
 /// to vary (for example, in antijoins).
 pub struct Relation<Tuple: Ord> {
+    /// Wrapped elements in the relation.
+    ///
+    /// It is crucial that if this type is constructed manually, this field be
+    /// sorted, and it is probably important that all elements be distinct.
     pub elements: Vec<Tuple>
 }
 
@@ -87,14 +96,30 @@ pub trait VariableTrait {
 }
 
 /// An monotonically increasing set of `Tuple`s.
+///
+/// The design here is that there are three types of tuples: i. those that have been
+/// processed by all operators that can access the variable, ii. those that should now
+/// be processed by all operators that can access the variable, and iii. those that
+/// have only just been added and should eventually be promoted to type ii. (but which
+/// are currently hidden).
+///
+/// Each time `self.changed()` is called, the `recent` relation is folded into `tuples`,
+/// and the `to_add` relations are merged, deduplicated against `tuples`, and then made
+/// `recent`. This way, across calls to `changed()` all added relations are at some point
+/// in `recent` once and eventually all are in `tuples`.
 pub struct Variable<Tuple: Ord> {
+    /// A useful name for the variable.
     pub name: String,
+    /// A list of relations whose union are the accepted tuples.
     pub tuples: Rc<RefCell<Vec<Relation<Tuple>>>>,
+    /// A list of recent tuples, still to be processed.
     pub recent: Rc<RefCell<Relation<Tuple>>>,
+    /// A list of future tuples, to be introduced.
     pub to_add: Rc<RefCell<Vec<Relation<Tuple>>>>,
 }
 
 impl<Tuple: Ord> Variable<Tuple> {
+    /// Adds tuples that result from joining `input1` and `input2`.
     pub fn from_join<K: Ord,V1: Ord, V2: Ord, F: Fn(&K,&V1,&V2)->Tuple>(
         &self,
         input1: &Variable<(K,V1)>,
@@ -103,6 +128,7 @@ impl<Tuple: Ord> Variable<Tuple> {
     {
         join::join_into(input1, input2, self, logic)
     }
+    /// Adds tuples that result from antijoining `input1` and `input2`.
     pub fn from_antijoin<K: Ord,V: Ord, F: Fn(&K,&V)->Tuple>(
         &self,
         input1: &Variable<(K,V)>,
@@ -111,7 +137,7 @@ impl<Tuple: Ord> Variable<Tuple> {
     {
         join::antijoin_into(input1, input2, self, logic)
     }
-
+    /// Adds tuples that result from mapping `input`.
     pub fn from_map<T2: Ord, F: Fn(&T2)->Tuple>(&self, input: &Variable<T2>, logic: F) {
         map::map_into(input, self, logic)
     }
@@ -137,9 +163,20 @@ impl<Tuple: Ord> Variable<Tuple> {
             to_add: Rc::new(RefCell::new(Vec::new().into())),
         }
     }
+    /// Inserts a relation into the variable.
+    ///
+    /// This is most commonly used to load initial values into a variable.
+    /// it is not obvious that it should be commonly used otherwise, but
+    /// it should not be harmful.
     pub fn insert(&self, relation: Relation<Tuple>) {
         self.to_add.borrow_mut().push(relation);
     }
+    /// Consumes the variable and returns a relation.
+    ///
+    /// This method removes the ability for the variable to develop, and
+    /// flattens all internal tuples down to one relation. The method
+    /// asserts that iteration has completed, in that `self.recent` and
+    /// `self.to_add` should both be empty.
     pub fn complete(self) -> Relation<Tuple> {
 
         assert!(self.recent.borrow().is_empty());

src/map.rs

@@ -1,3 +1,5 @@
+//! Map functionality.
+
 use super::Variable;
 
 pub fn map_into<T1: Ord, T2: Ord, F: Fn(&T1)->T2>(
@@ -12,4 +14,4 @@ pub fn map_into<T1: Ord, T2: Ord, F: Fn(&T1)->T2>(
     }
 
     output.insert(results.into());
-}
+}