Struct StatsManager 

pub struct StatsManager { /* private fields */ }

Manages GPU-resident statistics for all relations.

The StatsManager is the central repository for relation statistics and join selectivity information. It provides methods for:

• Registering new relations and tracking their statistics
• Updating cardinality and access patterns
• Estimating join cardinalities using cached selectivity data
• Managing relation “heat” for LRU-style eviction

Thread Safety

This type is not thread-safe. For concurrent access, wrap in appropriate synchronization primitives (e.g., RwLock).

Example

use xlog_stats::StatsManager;
use xlog_core::RelId;

let mut mgr = StatsManager::new();

// Register relations
mgr.register_relation(RelId(1));
mgr.register_relation(RelId(2));

// Update statistics
mgr.update_cardinality(RelId(1), 10_000);
mgr.update_cardinality(RelId(2), 5_000);

// Estimate join cardinality
let estimate = mgr.estimate_join_cardinality(RelId(1), RelId(2), &[0], &[0]);

Implementations

impl StatsManager

pub fn new() -> Self

Creates a new empty statistics manager.

Returns

A new StatsManager with no registered relations.

pub fn register_relation(&mut self, rel_id: RelId)

Registers a new relation for statistics tracking.

If the relation is already registered, this is a no-op.

Arguments

• rel_id - The unique identifier for the relation

pub fn snapshot(&self) -> StatsSnapshot

Create a snapshot of all currently tracked statistics.

pub fn merge_snapshot(&mut self, snapshot: &StatsSnapshot)

Merge a previously captured snapshot into this manager.

Existing entries are overwritten with the snapshot values.

pub fn unregister_relation(&mut self, rel_id: RelId) -> Option<RelationStats>

Unregisters a relation, removing all associated statistics.

Also removes any join selectivity entries involving this relation.

Arguments

• rel_id - The relation to unregister

Returns

The removed statistics if the relation was registered

pub fn get_relation_stats(&self, rel_id: RelId) -> Option<&RelationStats>

Gets immutable reference to relation statistics.

Arguments

• rel_id - The relation to look up

Returns

A reference to the statistics if the relation is registered

pub fn get_relation_stats_mut( &mut self, rel_id: RelId, ) -> Option<&mut RelationStats>

Gets mutable reference to relation statistics.

Arguments

• rel_id - The relation to look up

Returns

A mutable reference to the statistics if the relation is registered

pub fn update_cardinality(&mut self, rel_id: RelId, rows: u64)

Updates the cardinality (row count) for a relation.

If the relation is not registered, this is a no-op.

Arguments

• rel_id - The relation to update
• rows - The new cardinality estimate

pub fn update_byte_size(&mut self, rel_id: RelId, bytes: u64)

Updates the byte size estimate for a relation.

If the relation is not registered, this is a no-op.

Arguments

• rel_id - The relation to update
• bytes - The estimated total size in bytes

pub fn record_access(&mut self, rel_id: RelId)

Records an access to a relation, updating its heat and timestamp.

If the relation is not registered, this is a no-op.

Arguments

• rel_id - The relation that was accessed

pub fn add_column_stats(&mut self, rel_id: RelId, col_stats: ColumnStats)

Adds column statistics to a relation.

If the relation is not registered, this is a no-op.

Arguments

• rel_id - The relation to update
• col_stats - The column statistics to add

pub fn estimate_join_cardinality( &self, left_rel: RelId, right_rel: RelId, left_keys: &[usize], right_keys: &[usize], ) -> u64

Estimates the output cardinality for a join between two relations.

Uses cached selectivity if available, otherwise uses a default heuristic. The estimation formula is: left_card * right_card * selectivity.

Arguments

• left_rel - The left relation in the join
• right_rel - The right relation in the join
• left_keys - Column indices used as join keys on the left (currently for future use)
• right_keys - Column indices used as join keys on the right (currently for future use)

Returns

The estimated output cardinality (minimum of 1)

pub fn record_join_result( &mut self, left_rel: RelId, right_rel: RelId, left_keys: Vec<usize>, right_keys: Vec<usize>, input_rows: u64, output_rows: u64, )

Records the result of a join execution to improve future estimates.

Updates the selectivity model using exponential moving average: new_selectivity = old_selectivity * 0.7 + observed_selectivity * 0.3

Arguments

• left_rel - The left relation in the join
• right_rel - The right relation in the join
• left_keys - Column indices used as join keys on the left
• right_keys - Column indices used as join keys on the right
• input_rows - Product of input relation cardinalities
• output_rows - Actual output row count

pub fn set_join_selectivity( &mut self, left_rel: RelId, right_rel: RelId, left_keys: Vec<usize>, right_keys: Vec<usize>, selectivity: f64, )

Set (or overwrite) the join selectivity between two relations.

This is useful for seeding the optimizer from external observations (e.g., runtime stats).

pub fn get_join_selectivity( &self, left_rel: RelId, right_rel: RelId, ) -> Option<&JoinSelectivity>

Gets the cached join selectivity between two relations.

Arguments

• left_rel - One relation in the join
• right_rel - The other relation in the join

Returns

A reference to the cached selectivity if present

pub fn decay_all_heat(&mut self, factor: f32)

Decays the heat of all relations by a multiplicative factor.

This should be called periodically (e.g., during garbage collection or memory pressure events) to allow unused relations to cool down.

Arguments

• factor - Multiplicative decay factor (typically 0.0 to 1.0)

pub fn hot_relations(&self, threshold: f32) -> Vec<RelId>

Returns the IDs of all “hot” relations above a given heat threshold.

This is useful for identifying frequently accessed relations that should be kept in GPU memory.

Arguments

• threshold - The minimum heat value to be considered “hot”

Returns

A vector of RelIds for all relations with heat >= threshold

pub fn cold_relations(&self, threshold: f32) -> Vec<RelId>

Returns the IDs of all “cold” relations below a given heat threshold.

This is useful for identifying candidates for eviction from GPU memory.

Arguments

• threshold - The maximum heat value to be considered “cold”

Returns

A vector of RelIds for all relations with heat < threshold

pub fn relation_count(&self) -> usize

Returns the total number of registered relations.

pub fn relation_ids(&self) -> impl Iterator<Item = RelId> + '_

Returns an iterator over all registered relation IDs.

pub fn total_byte_size(&self) -> u64

Returns the total estimated bytes across all relations.

pub fn total_cardinality(&self) -> u64

Returns the total cardinality across all relations.

pub fn clear(&mut self)

Clears all statistics.

Removes all relation statistics and join selectivities.

Trait Implementations

impl Debug for StatsManager

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for StatsManager

fn default() -> StatsManager

Returns the “default value” for a type.