code and README

Author: arthurpaulino

README.md

@@ -1,5 +1,21 @@
 # cronos
 
+A lightweight, thread-safe timing profiler for Rust pipelines.  
+Track and visualize performance bottlenecks with minimal overhead.
+
+```rust
+cronos::clock("work"); // Start timer
+do_work();
+cronos::clock("work"); // Stop timer
+cronos::print();       // Display timeline
+```
+
+## Features
+
+- **Thread-Safe**: Global state protected by `Arc<Mutex<T>>`
+- **Visual Timeline**: ASCII-art bar chart scaled to terminal width
+- **Panic-on-Error**: Fails fast on misuse (duplicate tags, unfinished spans)
+
 ## License
 
 MIT or Apache 2.0

src/lib.rs

@@ -0,0 +1,227 @@
+use once_cell::sync::OnceCell;
+use rustc_hash::FxHashMap;
+use std::{
+    cmp::Ordering,
+    sync::{Arc, Mutex, MutexGuard},
+    time::Instant,
+};
+use terminal_size::{Width, terminal_size};
+
+enum Run {
+    Started(Instant),
+    Finished(Instant, Instant),
+}
+
+#[derive(Default)]
+struct Experiment {
+    start: Option<Instant>,
+    runs: FxHashMap<String, Run>,
+}
+
+static EXPERIMENT: OnceCell<Arc<Mutex<Experiment>>> = OnceCell::new();
+
+fn get_experiment() -> MutexGuard<'static, Experiment> {
+    EXPERIMENT
+        .get_or_init(|| Arc::new(Mutex::new(Experiment::default())))
+        .lock()
+        .expect("Failed to acquire lock")
+}
+
+/// Records or updates timing events for a labeled operation in a global
+/// experiment tracker.
+///
+/// This function is used to mark the **start** or **end** of a timed operation
+/// identified by `tag`.
+/// - On the **first call** with a given `tag`, it records a `Run::Started` event.
+/// - On the **second call** with the same `tag`, it updates the event to
+///   `Run::Finished` (with start/end times).
+/// - Panics if a `tag` is called more than twice (i.e., already finished).
+///
+/// # Global State
+/// The timing data is stored in a thread-safe global [`Experiment`] (accessed
+/// via [`Arc`] + [`Mutex`]).
+///
+/// The experiment's global start time is set on the first call to `clock`.
+///
+/// # Panics
+/// - If a `tag` is used after it has already been marked `Finished`.
+/// - If the global [`Mutex`] is poisoned by another thread.
+///
+/// # Example
+/// ```rust
+/// cronos::clock("work"); // Start tracking "work"
+/// do_work();
+/// cronos::clock("work"); // Finish tracking "work" (start → end)
+/// ```
+///
+/// # Performance
+/// - Uses [`FxHashMap`] for efficient string-keyed lookups.
+/// - Locks the global [`Mutex`] briefly during updates.
+pub fn clock(tag: impl AsRef<str>) {
+    let mut experiment = get_experiment();
+    let now = Instant::now();
+    if experiment.start.is_none() {
+        experiment.start = Some(now);
+    }
+    let tag = tag.as_ref();
+    if let Some(run) = experiment.runs.get_mut(tag) {
+        match run {
+            Run::Finished(..) => panic!("{tag} is already finished."),
+            Run::Started(start) => *run = Run::Finished(*start, now),
+        }
+    } else {
+        experiment.runs.insert(tag.to_string(), Run::Started(now));
+    }
+}
+
+#[allow(clippy::cast_precision_loss)]
+fn format_duration(nanos: u128) -> String {
+    if nanos < 1_000 {
+        format!("{nanos}ns")
+    } else if nanos < 1_000_000 {
+        format!("{:.2}μs", nanos as f64 / 1_000.0)
+    } else if nanos < 1_000_000_000 {
+        format!("{:.2}ms", nanos as f64 / 1_000_000.0)
+    } else if nanos < 60_000_000_000 {
+        format!("{:.2}s", nanos as f64 / 1_000_000_000.0)
+    } else if nanos < 3_600_000_000_000 {
+        let secs = nanos as f64 / 1_000_000_000.0;
+        format!("{:.2}m", secs / 60.0)
+    } else {
+        let secs = nanos as f64 / 1_000_000_000.0;
+        format!("{:.2}h", secs / 3_600.0)
+    }
+}
+
+struct RunStats<'a> {
+    tag: &'a str,
+    tag_len: usize,
+    to_start_ns: u128,
+    duration_ns: u128,
+    duration_fmt: String,
+    duration_fmt_len: usize,
+}
+
+/// Prints a visual timeline of all completed experiment runs to the terminal.
+///
+/// Displays a horizontal bar chart showing:
+/// - Relative timing of each run (position along the x-axis)
+/// - Duration of each run (length of the bar)
+/// - Absolute durations in human-readable format
+///
+/// # Behavior
+/// - Only prints if:
+///   * A TTY is detected (via `terminal_size()`)
+///   * At least one experiment has been started (`clock(<tag>)` called)
+///   * All tracked tags have been properly finished
+/// - Automatically scales the timeline to fit the terminal width
+/// - Includes a summary bar for the total experiment duration
+///
+/// # Panics
+/// - If any tracked tag hasn't been finished (missing `clock(<tag>)` call)
+/// - If terminal width would cause arithmetic overflow (extremely unlikely)
+///
+/// # Example Output
+/// ```text
+///         │1.62s   ├─────────────────────────────────────────────────────────┤
+/// s1commit│302.69ms├──────────┤
+/// s2traces│37.97ms            ├┤
+/// s2commit│196.21ms            ├──────┤
+/// qcommit │527.96ms                   ├──────────────────┤
+/// qeval-0 │135.20ms                   ├───┤
+/// qeval-1 │73.02ms                              ├─┤
+/// open    │554.95ms                                      ├───────────────────┤
+/// ```
+pub fn print() {
+    let Some((Width(terminal_width), _)) = terminal_size() else {
+        return; // No TTY available
+    };
+
+    // Gather data from runs
+    let experiment = get_experiment();
+    let Some(experiment_start) = experiment.start else {
+        return; // No experiment performed
+    };
+    let mut experiment_end = experiment_start;
+    let mut biggest_tag_len = 0;
+    let mut biggest_duration_fmt_len = 0;
+    let mut finished_runs = Vec::with_capacity(experiment.runs.len());
+    for (tag, run) in &experiment.runs {
+        let tag_len = tag.chars().count();
+        biggest_tag_len = biggest_tag_len.max(tag_len);
+        let Run::Finished(start, end) = run else {
+            panic!("{tag} is not finished.");
+        };
+        if end > &experiment_end {
+            experiment_end = *end; // .max wouldn't avoid this copy
+        }
+        let duration_ns = (*end - *start).as_nanos();
+        let duration_fmt = format_duration(duration_ns);
+        let duration_fmt_len = duration_fmt.chars().count();
+        biggest_duration_fmt_len = biggest_duration_fmt_len.max(duration_fmt_len);
+        let stats = RunStats {
+            tag,
+            tag_len,
+            to_start_ns: (*start - experiment_start).as_nanos(),
+            duration_ns,
+            duration_fmt,
+            duration_fmt_len,
+        };
+        finished_runs.push(stats);
+    }
+    let experiment_duration_ns = (experiment_end - experiment_start).as_nanos();
+    let experiment_duration_fmt = format_duration(experiment_duration_ns);
+    let experiment_duration_fmt_len = experiment_duration_fmt.chars().count();
+    biggest_duration_fmt_len = biggest_duration_fmt_len.max(experiment_duration_fmt_len);
+
+    // Push the stats for the full experiment and then sort
+    finished_runs.push(RunStats {
+        tag: "",
+        tag_len: 0,
+        to_start_ns: 0,
+        duration_ns: experiment_duration_ns,
+        duration_fmt: experiment_duration_fmt,
+        duration_fmt_len: experiment_duration_fmt_len,
+    });
+    finished_runs.sort_by(|a, b| {
+        if a.to_start_ns < b.to_start_ns {
+            Ordering::Less
+        } else if a.to_start_ns == b.to_start_ns {
+            b.duration_ns.cmp(&a.duration_ns)
+        } else {
+            Ordering::Greater
+        }
+    });
+
+    // Finally print the duration bars
+    let width = // Consider the vertical pipe that separates tags and durations
+        (terminal_width as usize).saturating_sub(biggest_tag_len + biggest_duration_fmt_len + 1);
+    let width_u128 = width as u128;
+    let transform = |x: u128| (x * width_u128).div_ceil(experiment_duration_ns);
+    for run in finished_runs {
+        let RunStats {
+            tag,
+            tag_len,
+            to_start_ns,
+            duration_ns,
+            duration_fmt,
+            duration_fmt_len,
+        } = run;
+
+        let bar_pos = usize::try_from(transform(to_start_ns)).unwrap();
+        let bar_len = usize::try_from(transform(duration_ns)).unwrap();
+
+        let bar = match bar_len {
+            0 => "│".to_string(),
+            1 => "┃".to_string(),
+            _ => format!("├{}┤", "─".repeat(bar_len - 2)),
+        };
+
+        println!(
+            "{tag}{}│{duration_fmt}{}{}{bar}",
+            " ".repeat(biggest_tag_len - tag_len),
+            " ".repeat(biggest_duration_fmt_len - duration_fmt_len),
+            " ".repeat(bar_pos.saturating_sub(1)),
+        );
+    }
+}