pub trait PathSummary<T>:
Clone
+ 'static
+ Eq
+ PartialOrder
+ Debug
+ Default {
// Required methods
fn results_in(&self, src: &T) -> Option<T>;
fn followed_by(&self, other: &Self) -> Option<Self>;
}
Expand description
A summary of how a timestamp advances along a timely dataflow path.
Required Methods§
Sourcefn results_in(&self, src: &T) -> Option<T>
fn results_in(&self, src: &T) -> Option<T>
Advances a timestamp according to the timestamp actions on the path.
The path may advance the timestamp sufficiently that it is no longer valid, for example if
incrementing fields would result in integer overflow. In this case, results_in
should
return None
.
The feedback
operator, apparently the only point where timestamps are actually incremented
in computation, uses this method and will drop messages with timestamps that when advanced
result in None
. Ideally, all other timestamp manipulation should behave similarly.
This function must be monotonic increasing in both inputs.
If s1.less_equal(&s2)
then for all t
we have s1.results_in(&t).less_equal(&s2.results_in(&t))
.
If t1.less_equal(&t2)
then for all s
we have s.results_in(&t1).less_equal(&s.results_in(&t2))
.
Note that Self::default()
is expected to behave as an “empty” or “noop” summary, such that
Self::default().results_in(&t) == Some(t)
. The default summary does not need to be a minimal
summary, in that summaries are technically permitted to walk timestamps backwards. Care should
be used when doing this to avoid potentially cyclic dataflows without strict timestamp advancement.
§Examples
use timely::progress::timestamp::PathSummary;
let timestamp = 3;
let summary1 = 5;
let summary2 = usize::MAX - 2;
assert_eq!(summary1.results_in(×tamp), Some(8));
assert_eq!(summary2.results_in(×tamp), None);
Sourcefn followed_by(&self, other: &Self) -> Option<Self>
fn followed_by(&self, other: &Self) -> Option<Self>
Composes this path summary with another path summary.
It is possible that the two composed paths result in an invalid summary, for example when
integer additions overflow. If it is correct that all timestamps moved along these paths
would also result in overflow and be discarded, followed_by
can return None
. It is very
important that this not be used casually, as this does not prevent the actual movement of
data.
Calling results_in
on the composed summary should behave the same as though the two
summaries were applied to the argument in order.
§Examples
use timely::progress::timestamp::PathSummary;
let summary1 = 5;
let summary2 = usize::MAX - 3;
assert_eq!(summary1.followed_by(&summary2), None);
let time = 10;
let summary2 = 15;
assert_eq!(
// Applying the composed summary...
summary1.followed_by(&summary2).and_then(|s| s.results_in(&time)),
// ...has the same result as applying the two summaries in sequence.
summary1.results_in(&time).and_then(|t| summary2.results_in(&t)),
);
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.