diff --git a/src/collection.rs b/src/collection.rs index f2daf8ad4..fd6dd80d7 100644 --- a/src/collection.rs +++ b/src/collection.rs @@ -42,6 +42,10 @@ pub struct Collection { /// /// This field is exposed to support direct timely dataflow manipulation when required, but it is /// not intended to be the idiomatic way to work with the collection. + /// + /// The timestamp in the data is required to always be at least the timestamp _of_ the data, in + /// the timely-dataflow sense. If this invariant is not upheld, differential operators may behave + /// unexpectedly. pub inner: Stream } @@ -52,6 +56,9 @@ impl Collection where G::Timestamp: Da /// idiomatic approach to convert timely streams to collections. Also, the `input::Input` trait /// provides a `new_collection` method which will create a new collection for you without exposing /// the underlying timely stream at all. + /// + /// This stream should satisfy the timestamp invariant as documented on [Collection]; this + /// method does not check it. pub fn new(stream: Stream) -> Collection { Collection { inner: stream } } @@ -356,8 +363,9 @@ impl Collection where G::Timestamp: Da /// /// It is assumed that `func` only advances timestamps; this is not verified, and things may go horribly /// wrong if that assumption is incorrect. It is also critical that `func` be monotonic: if two times are - /// ordered, they should have the same order once `func` is applied to them (this is because we advance the - /// timely capability with the same logic, and it must remain `less_equal` to all of the data timestamps). + /// ordered, they should have the same order or compare equal once `func` is applied to them (this + /// is because we advance the timely capability with the same logic, and it must remain `less_equal` + /// to all of the data timestamps). pub fn delay(&self, func: F) -> Collection where F: FnMut(&G::Timestamp) -> G::Timestamp + Clone + 'static { @@ -369,6 +377,7 @@ impl Collection where G::Timestamp: Da .map_in_place(move |x| x.1 = func2(&x.1)) .as_collection() } + /// Applies a supplied function to each update. /// /// This method is most commonly used to report information back to the user, often for debugging purposes. @@ -599,6 +608,10 @@ pub trait AsCollection { } impl AsCollection for Stream { + /// Converts the type to a differential dataflow collection. + /// + /// By calling this method, you guarantee that the timestamp invariant (as documented on + /// [Collection]) is upheld. This method will not check it. fn as_collection(&self) -> Collection { Collection::new(self.clone()) } diff --git a/src/lattice.rs b/src/lattice.rs index 980798764..938669bcd 100644 --- a/src/lattice.rs +++ b/src/lattice.rs @@ -27,6 +27,7 @@ pub trait Lattice : PartialOrder { /// assert_eq!(join, Product::new(4, 7)); /// # } /// ``` + #[must_use] fn join(&self, other: &Self) -> Self; /// Updates `self` to the smallest element greater than or equal to both arguments. @@ -67,6 +68,7 @@ pub trait Lattice : PartialOrder { /// assert_eq!(meet, Product::new(3, 6)); /// # } /// ``` + #[must_use] fn meet(&self, other: &Self) -> Self; /// Updates `self` to the largest element less than or equal to both arguments.