sorting_race/models/
traits.rs

1//! Core traits for the sorting race visualization
2
3use std::any::Any;
4use std::fmt::Debug;
5
6/// Result of a single step execution
7#[derive(Debug, Clone, PartialEq)]
8pub struct StepResult {
9    /// Number of comparisons performed in this step
10    pub comparisons_used: usize,
11    /// Number of element moves performed in this step
12    pub moves_made: usize,
13    /// Whether the algorithm needs more steps
14    pub continued: bool,
15}
16
17/// Visual markers for algorithm-specific operations
18#[derive(Debug, Clone, Default)]
19pub struct Markers {
20    /// Current pivot index (Quick Sort)
21    pub pivot: Option<usize>,
22    /// Heap/sorted boundary (Heap Sort)
23    pub heap_boundary: Option<usize>,
24    /// Active merge regions (Merge Sort)
25    pub merge_runs: Vec<(usize, usize)>,
26    /// Current comparison positions
27    pub cursors: Vec<usize>,
28    /// Current gap size (Shell Sort)
29    pub gap: Option<usize>,
30}
31
32/// Telemetry data returned after each step
33#[derive(Debug, Clone)]
34pub struct Telemetry {
35    /// Total comparisons so far
36    pub total_comparisons: u64,
37    /// Total moves so far
38    pub total_moves: u64,
39    /// Current auxiliary memory usage in bytes
40    pub memory_current: usize,
41    /// Peak auxiliary memory usage in bytes
42    pub memory_peak: usize,
43    /// Indices to highlight in visualization
44    pub highlights: Vec<usize>,
45    /// Algorithm-specific markers
46    pub markers: Markers,
47    /// Human-readable description of current operation
48    pub status_text: String,
49    /// Progress estimate (0.0 to 1.0)
50    pub progress_hint: f32,
51}
52
53/// Core trait that all sorting algorithms must implement
54pub trait Sorter: Debug + Send + Any {
55    /// Execute one step of the sorting algorithm
56    /// 
57    /// # Arguments
58    /// * `budget` - Maximum number of comparisons allowed in this step
59    /// 
60    /// # Returns
61    /// * `StepResult` - Information about operations performed
62    fn step(&mut self, budget: usize) -> StepResult;
63    
64    /// Check if the algorithm has completed sorting
65    fn is_complete(&self) -> bool;
66    
67    /// Get current telemetry data
68    fn get_telemetry(&self) -> Telemetry;
69    
70    /// Reset the algorithm with new data
71    /// 
72    /// # Arguments
73    /// * `data` - New array to sort
74    fn reset(&mut self, data: Vec<i32>);
75    
76    /// Get the algorithm's display name
77    fn name(&self) -> &str;
78    
79    /// Get current array state (for visualization)
80    fn get_array(&self) -> &[i32];
81    
82    /// Get auxiliary memory usage in bytes
83    fn get_memory_usage(&self) -> usize;
84    
85    /// Support downcasting for type-specific operations
86    fn as_any(&self) -> &dyn Any;
87    
88    /// Support mutable downcasting for type-specific operations
89    fn as_any_mut(&mut self) -> &mut dyn Any;
90}
91
92/// Fairness model trait for allocating step budgets
93pub trait FairnessModel: Debug {
94    /// Allocate step budgets to algorithms
95    /// 
96    /// # Arguments
97    /// * `algorithms` - Current state of all algorithms
98    /// 
99    /// # Returns
100    /// * Vector of budgets (comparisons) for each algorithm
101    fn allocate_budget(&self, algorithms: &[Box<dyn Sorter>]) -> Vec<usize>;
102    
103    /// Get the model's display name
104    fn name(&self) -> &str;
105}
106
107/// Memory tracker for precise auxiliary space measurement
108pub trait MemoryTracker: Debug {
109    /// Record an allocation
110    fn alloc(&mut self, bytes: usize);
111    
112    /// Record a deallocation
113    fn free(&mut self, bytes: usize);
114    
115    /// Get current memory usage
116    fn current(&self) -> usize;
117    
118    /// Get peak memory usage
119    fn peak(&self) -> usize;
120    
121    /// Reset tracking
122    fn reset(&mut self);
123}
sorting_race/models/traits.rs

sorting_race/models/
traits.rs
