pub trait BatchReader:
Debug
+ NumEntries
+ Rkyv
+ SizeOf
+ 'staticwhere
Self: Sized,{
type Factories: BatchFactories<Self::Key, Self::Val, Self::Time, Self::R>;
type Key: DataTrait + ?Sized;
type Val: DataTrait + ?Sized;
type Time: Timestamp;
type R: WeightTrait + ?Sized;
type Cursor<'s>: Cursor<Self::Key, Self::Val, Self::Time, Self::R> + Clone + Send
where Self: 's;
Show 17 methods
// Required methods
fn factories(&self) -> Self::Factories;
fn cursor(&self) -> Self::Cursor<'_>;
fn key_count(&self) -> usize;
fn len(&self) -> usize;
fn approximate_byte_size(&self) -> usize;
fn filter_stats(&self) -> BloomFilterStats;
fn sample_keys<RG>(
&self,
rng: &mut RG,
sample_size: usize,
sample: &mut DynVec<Self::Key>,
)
where Self::Time: PartialEq<()>,
RG: Rng;
// Provided methods
fn push_cursor(
&self,
) -> Box<dyn PushCursor<Self::Key, Self::Val, Self::Time, Self::R> + Send + '_> { ... }
fn merge_cursor(
&self,
key_filter: Option<Filter<Self::Key>>,
value_filter: Option<GroupFilter<Self::Val>>,
) -> Box<dyn MergeCursor<Self::Key, Self::Val, Self::Time, Self::R> + Send + '_> { ... }
fn merge_cursor_with_snapshot<'a, S>(
&'a self,
key_filter: Option<Filter<Self::Key>>,
value_filter: Option<GroupFilter<Self::Val>>,
snapshot: &'a Option<Arc<S>>,
) -> Box<dyn MergeCursor<Self::Key, Self::Val, Self::Time, Self::R> + Send + 'a>
where S: BatchReader<Key = Self::Key, Val = Self::Val, Time = Self::Time, R = Self::R> { ... }
fn consuming_cursor(
&mut self,
key_filter: Option<Filter<Self::Key>>,
value_filter: Option<GroupFilter<Self::Val>>,
) -> Box<dyn MergeCursor<Self::Key, Self::Val, Self::Time, Self::R> + Send + '_> { ... }
fn location(&self) -> BatchLocation { ... }
fn cache_stats(&self) -> CacheStats { ... }
fn is_empty(&self) -> bool { ... }
fn maybe_contains_key(&self, _hash: u64) -> bool { ... }
async fn fetch<B>(
&self,
keys: &B,
) -> Option<Box<dyn CursorFactory<Self::Key, Self::Val, Self::Time, Self::R>>>
where B: BatchReader<Key = Self::Key, Time = ()> { ... }
fn keys(&self) -> Option<&DynVec<Self::Key>> { ... }
}Expand description
A set of (key, value, time, diff) tuples whose contents may be read in
order by key and value.
A BatchReader is a mostly read-only interface. This is especially useful
for views derived from other sources in ways that prevent the construction
of batches from the type of data in the view (for example, filtered views,
or views with extended time coordinates).
See crate documentation for more information on batches and traces.
§Object safety
BatchReader is not object safe (it cannot be used as dyn BatchReader),
but Cursor is, which can often be a useful substitute.
Required Associated Types§
type Factories: BatchFactories<Self::Key, Self::Val, Self::Time, Self::R>
Sourcetype R: WeightTrait + ?Sized
type R: WeightTrait + ?Sized
Associated update.
Required Methods§
fn factories(&self) -> Self::Factories
Sourcefn approximate_byte_size(&self) -> usize
fn approximate_byte_size(&self) -> usize
The memory or storage size of the batch in bytes.
This can be an approximation, such as the size of an on-disk file for a stored batch.
Implementations of this function can be expensive because they might require iterating through all the data in a batch. Currently this is only used to decide whether to keep the result of a merge in memory or on storage. For this case, the merge will visit and copy all the data in the batch. The batch will be discarded afterward, which means that the implementation need not attempt to cache the return value.
Sourcefn filter_stats(&self) -> BloomFilterStats
fn filter_stats(&self) -> BloomFilterStats
Statistics of the Bloom filter used by Cursor::seek_key_exact.
The Bloom filter (kept in memory) is used there to quickly check
whether a key might be present in the batch, before doing a
binary tree lookup within the batch to be exactly sure.
The statistics include for example the size in bytes and the hit rate.
Only some kinds of batches use a filter; others should return
BloomFilterStats::default().
Sourcefn sample_keys<RG>(
&self,
rng: &mut RG,
sample_size: usize,
sample: &mut DynVec<Self::Key>,
)
fn sample_keys<RG>( &self, rng: &mut RG, sample_size: usize, sample: &mut DynVec<Self::Key>, )
Returns a uniform random sample of distincts keys from the batch.
Does not take into account the number values associated with each key and their weights, i.e., a key that has few values is as likely to appear in the output sample as a key with many values.
§Arguments
-
rng- random number generator used to generate the sample. -
sample_size- requested sample size. -
sample- output
§Invariants
The actual sample computed by the method can be smaller than
sample_size even if self contains >sample_size keys.
A correct implementation must enforce the following invariants:
-
The output sample size cannot exceed
sample_size. -
The output sample can only contain keys present in
self(with non-zero weights). -
If
sample_sizeis greater than or equal to the number of keys present inself(with non-zero weights), the resulting sample must contain all such keys. -
The output sample contains keys sorted in ascending order.
Provided Methods§
Sourcefn push_cursor(
&self,
) -> Box<dyn PushCursor<Self::Key, Self::Val, Self::Time, Self::R> + Send + '_>
fn push_cursor( &self, ) -> Box<dyn PushCursor<Self::Key, Self::Val, Self::Time, Self::R> + Send + '_>
Acquires a PushCursor for the batch’s contents.
Sourcefn merge_cursor(
&self,
key_filter: Option<Filter<Self::Key>>,
value_filter: Option<GroupFilter<Self::Val>>,
) -> Box<dyn MergeCursor<Self::Key, Self::Val, Self::Time, Self::R> + Send + '_>
fn merge_cursor( &self, key_filter: Option<Filter<Self::Key>>, value_filter: Option<GroupFilter<Self::Val>>, ) -> Box<dyn MergeCursor<Self::Key, Self::Val, Self::Time, Self::R> + Send + '_>
Acquires a MergeCursor for the batch’s contents.
Sourcefn merge_cursor_with_snapshot<'a, S>(
&'a self,
key_filter: Option<Filter<Self::Key>>,
value_filter: Option<GroupFilter<Self::Val>>,
snapshot: &'a Option<Arc<S>>,
) -> Box<dyn MergeCursor<Self::Key, Self::Val, Self::Time, Self::R> + Send + 'a>
fn merge_cursor_with_snapshot<'a, S>( &'a self, key_filter: Option<Filter<Self::Key>>, value_filter: Option<GroupFilter<Self::Val>>, snapshot: &'a Option<Arc<S>>, ) -> Box<dyn MergeCursor<Self::Key, Self::Val, Self::Time, Self::R> + Send + 'a>
Similar to merge_cursor, but invoked in the context of a spine merger.
Takes the current spine snapshot as an extra argument and uses it to evaluate value_filter precisely.
Sourcefn consuming_cursor(
&mut self,
key_filter: Option<Filter<Self::Key>>,
value_filter: Option<GroupFilter<Self::Val>>,
) -> Box<dyn MergeCursor<Self::Key, Self::Val, Self::Time, Self::R> + Send + '_>
fn consuming_cursor( &mut self, key_filter: Option<Filter<Self::Key>>, value_filter: Option<GroupFilter<Self::Val>>, ) -> Box<dyn MergeCursor<Self::Key, Self::Val, Self::Time, Self::R> + Send + '_>
Acquires a merge cursor for the batch’s contents.
Sourcefn location(&self) -> BatchLocation
fn location(&self) -> BatchLocation
Where the batch’s data is stored.
Sourcefn cache_stats(&self) -> CacheStats
fn cache_stats(&self) -> CacheStats
Storage cache access statistics for this batch only.
Most batches are in-memory, so they don’t have any statistics.
Sourcefn maybe_contains_key(&self, _hash: u64) -> bool
fn maybe_contains_key(&self, _hash: u64) -> bool
A method that returns either true (possibly in the batch) or false (definitely not in the batch).
Sourceasync fn fetch<B>(
&self,
keys: &B,
) -> Option<Box<dyn CursorFactory<Self::Key, Self::Val, Self::Time, Self::R>>>
async fn fetch<B>( &self, keys: &B, ) -> Option<Box<dyn CursorFactory<Self::Key, Self::Val, Self::Time, Self::R>>>
Creates and returns a new batch that is a subset of this one, containing
only the key-value pairs whose keys are in keys. May also return
None, the default implementation, if the batch doesn’t want to
implement this method. In particular, a batch for which access through
a cursor is fast should return None to avoid the expense of copying
data.
§Rationale
This method enables performance optimizations for the case where these assumptions hold:
-
Individual Batches flowing through a circuit are small enough to fit comfortably in memory.
-
Traces accumulated over time as a circuit executes may become large enough that they must be maintained in external storage.
If an operator needs to fetch all of the data from a trace that
corresponds to some set of keys, then, given these assumptions, doing
so one key at a time with a cursor will be slow because every key fetch
potentially incurs a round trip to the storage, with total latency O(n)
in the number of keys. This method gives the batch implementation the
opportunity to implement parallel fetch for trace.fetch(key), with
total latency O(1) in the number of keys.
fn keys(&self) -> Option<&DynVec<Self::Key>>
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.