### glassbench Macro Usage

Source: https://docs.rs/glassbench/latest/glassbench/macro.glassbench.html

Example of invoking the glassbench macro with a title and a list of benchmark functions.

```rust
glassbench!(
    "Sortings",
    bench_number_sorting,
    bench_alpha_sorting,
);
```

--------------------------------

### Bench::task usage example

Source: https://docs.rs/glassbench/latest/glassbench/struct.Bench.html

Example of defining a benchmark task using the task method.

```rust
bench.task("answer 42", |task| {
    let computer = BigComputer::new();
    let question = 42;
    task.iter(|| {
        pretend_used(computer.answer(question));
    });
});
```

--------------------------------

### TaskBench::iter

Source: https://docs.rs/glassbench/latest/glassbench/struct.TaskBench.html

Calls the provided function to measure its execution time. Includes an initial warmup and runs the function enough times to get a reliable duration estimate.

```APIDOC
## TaskBench::iter

### Description
Calls the provided function to measure its execution time. Includes an initial warmup and runs the function enough times to get a reliable duration estimate.

### Method
iter

### Signature
pub fn iter<M, R>(&mut self, measured: M) where M: FnMut() -> R

### Parameters
- **measured** (M) - Required - The closure to be measured. It must implement FnMut() -> R.

### Return Value
No return value (unit type).
```

--------------------------------

### Db::open

Source: https://docs.rs/glassbench/latest/glassbench/struct.Db.html

Creates a new instance of Db, creating the SQLite file and the tables if necessary.

```APIDOC
## Db::open

### Description
Creates a new instance of Db, creating the SQLite file and the tables if necessary.

### Method
open()

### Signature
pub fn open() -> Result<Self, GlassBenchError>

### Returns
- Result<Self, GlassBenchError> - A new Db instance or an error.
```

--------------------------------

### TaskBench implementation methods

Source: https://docs.rs/glassbench/latest/src/glassbench/task_bench.rs.html

Provides methods for initializing a new TaskBench, calculating differences between benchmarks, and executing the measurement iteration logic.

```rust
impl TaskBench {
    pub(crate) fn new(name: String) -> Self {
        Self {
            name,
            measure: None,
        }
    }

    pub(crate) fn diff_with(&self, old_bench: &Bench) -> Option<TaskBenchDiff> {
        old_bench
            .tasks
            .iter()
            .find(|tb| tb.name == self.name)
            .and_then(|old_tb| old_tb.measure)
            .and_then(|old_mes| {
                self.measure
                    .map(|new_mes| TaskBenchDiff::new(old_mes, new_mes))
            })
    }

    /// Call the function to measure
    ///
    /// There will be an initial warmup, after which
    /// the function will be called enought times to
    /// get a reliable estimation of its duration.
    pub fn iter<M, R>(&mut self, mut measured: M)
    where
        M: FnMut() -> R,
    {
        if self.measure.is_some() {
            eprintln!("bench already used - please fix your benchmark");
            return;
        }
        // just a warmup
        for _ in 0..WARMUP_ITERATIONS {
            measured();
        }
        // first estimation, to compute the number of iterations later
        let start = Instant::now();
        for _ in 0..ESTIMATE_ITERATIONS {
            measured();
        }
        let estimate_ns = start.elapsed().as_nanos();
        let iterations = ((OPTIMAL_DURATION_NS * ESTIMATE_ITERATIONS as u128) / estimate_ns)
            .try_into()
            .unwrap_or(MINIMAL_ITERATIONS)
            .max(MINIMAL_ITERATIONS);
        // now we do the real measure
        let start = Instant::now();
        for _ in 0..iterations {
            measured();
        }
        let total_duration = start.elapsed();
        self.measure = Some(TaskMeasure {
            iterations,
            total_duration,
        });
    }
}
```

--------------------------------

### Printer::new

Source: https://docs.rs/glassbench/latest/glassbench/struct.Printer.html

Creates a new Printer instance. The skin will be without style and color if the output is piped.

```APIDOC
## Printer::new

### Description
Creates a new Printer instance. The skin will be without style and color if the output is piped.

### Method
pub fn new() -> Self

### Parameters
None

### Returns
Self - A new Printer instance.
```

--------------------------------

### Bench::new

Source: https://docs.rs/glassbench/latest/glassbench/struct.Bench.html

Creates a new Bench instance with a specific name and title. This method is typically not used directly; the glassbench! macro is preferred.

```APIDOC
## Bench::new

### Description
Creates a new Bench instance with a specific name and title. This method is typically not used directly; the glassbench! macro is preferred.

### Method
new

### Signature
pub fn new<S1, S2>(name: S1, title: S2) -> Self
where S1: Into<String>, S2: Into<String>

### Parameters
- **name** (S1) - Required - The name of the benchmark.
- **title** (S2) - Required - The title of the benchmark.

### Returns
- **Self** - A new Bench instance.

```

--------------------------------

### after_bench(bench: &mut Bench, cmd: &Command) -> Result<(), GlassBenchError>

Source: https://docs.rs/glassbench/latest/glassbench/fn.after_bench.html

Prints the tabular report for the executed benchmark and then graphs, lists history, or saves according to the command. Returns a Result indicating success or a GlassBenchError.

```APIDOC
## after_bench(bench: &mut Bench, cmd: &Command) -> Result<(), GlassBenchError>

### Description
Prints the tabular report for the executed benchmark and then graphs, lists history, or saves according to the command. Unless you have special reasons, you should not use this function but the glassbench! function.

### Function Signature
pub fn after_bench(
    bench: &mut Bench,
    cmd: &Command,
) -> Result<(), GlassBenchError>

### Parameters
- **bench** (&mut Bench) - Required - A mutable reference to the Bench object representing the executed benchmark.
- **cmd** (&Command) - Required - A reference to the Command object that determines whether to graph, list history, or save.

### Return Value
- **Result<(), GlassBenchError>** - Returns Ok(()) on success, or an Err containing a GlassBenchError on failure.

### Usage Notes
This function is intended for advanced use cases. For typical usage, prefer the glassbench! macro.
```

--------------------------------

### Bench::new constructor

Source: https://docs.rs/glassbench/latest/src/glassbench/bench.rs.html

Creates a new benchmark instance. It is recommended to use the glassbench! macro instead of calling this directly.

```rust
impl Bench {
    /// Create a benchmark with a specific name and title
    ///
    /// You normally create don't use this function but the `glassbench!`
    /// macro which will fetch the id in the name of the executed benchmark.
    pub fn new<S1, S2>(name: S1, title: S2) -> Self
    where
        S1: Into<String>,
        S2: Into<String>,
    {
        Self {
            time: Utc::now(),
            name: name.into(),
            title: title.into(),
            tasks: Vec::new(),
            tag: None,
            git_info: GitInfo::read(),
        }
    }
```

--------------------------------

### create_bench

Source: https://docs.rs/glassbench/latest/glassbench/fn.create_bench.html

Creates a Bench with a user-defined name and command. This function is intended for special cases; the glassbench! macro is recommended for typical usage.

```APIDOC
## create_bench

### Description
Creates a Bench with a user-defined name and command, instead of using the file name and command read from arguments. This function is provided for special cases; the glassbench! macro is recommended for normal usage.

### Signature
pub fn create_bench<S1, S2>(name: S1, title: S2, cmd: &Command) -> Bench
where
    S1: Into<String>,
    S2: Into<String>,

### Parameters
- **name** (S1) - Required - The user-defined name for the bench.
- **title** (S2) - Required - The title for the bench.
- **cmd** (&Command) - Required - The command to run for the bench.

### Returns
- **Bench** - The created Bench instance.

### Notes
Unless you have special reasons, you should not use this function but the glassbench! function.
```

--------------------------------

### HtmlViewer::new

Source: https://docs.rs/glassbench/latest/glassbench/struct.HtmlViewer.html

Creates a new HtmlViewer instance with the given benchmark name and optional task name.

```APIDOC
## HtmlViewer::new

### Description
Creates a new HtmlViewer instance with the given benchmark name and optional task name.

### Signature
pub fn new(bench_name: &'b str, task_name: Option<&'b str>) -> Self

### Parameters
- **bench_name** (&'b str) - Required - The name of the benchmark.
- **task_name** (Option<&'b str>) - Optional - The name of the task, if any.

### Returns
- **Self** - A new HtmlViewer instance.
```

--------------------------------

### HTML Viewer Implementation

Source: https://docs.rs/glassbench/latest/src/glassbench/html_viewer.rs.html

The core implementation for building and writing the standalone HTML viewer, including resource embedding and configuration serialization.

```rust
use {
    crate::*,
    serde::Serialize,
    std::{
        fs::File,
        io::{self, Read},
        path::PathBuf,
    },
};

pub const DOLL_JS: &str = include_str!("../rsc/dom-doll.js");
pub const VIS_JS: &str = include_str!("../rsc/vis-timeline-graph2d.min.js");
pub const VIS_CSS: &str = include_str!("../rsc/vis-timeline-graph2d.min.css");
pub const SQL_JS: &str = include_str!("../rsc/sql-wasm.js");
pub const SQL_WASM: &[u8] = include_bytes!("../rsc/sql-wasm.wasm");
pub const VIEWER_JS: &str = include_str!("../rsc/viewer.js");
pub const VIEWER_CSS: &str = include_str!("../rsc/viewer.css");

/// configuration sent to the html page in JSON
#[derive(Debug, Serialize)]
struct Conf<'b> {
    bench_name: &'b str,
    task_name: Option<&'b str>,
    gb_version: String,
}

/// The builder of the HTML standalone viewer
pub struct HtmlViewer<'b> {
    conf: Conf<'b>,
}

impl<'b> HtmlViewer<'b> {
    pub fn new(bench_name: &'b str, task_name: Option<&'b str>) -> Self {
        Self {
            conf: Conf {
                bench_name,
                task_name,
                gb_version: env!("CARGO_PKG_VERSION").to_string(),
            },
        }
    }

    pub fn open_in_browser(&self) -> Result<(), GlassBenchError> {
        let (mut w, path) = make_temp_file()?;
        self.write_html(&mut w)?;
        open::that(path)?;
        Ok(())
    }

    pub fn write_html<W: io::Write>(&self, mut w: W) -> Result<(), GlassBenchError> {
        writeln!(w, "<!DOCTYPE HTML>")?;
        writeln!(w, "<html>")?;
        writeln!(w, "<head>")?;
        writeln!(w, "<meta charset=UTF-8>")?;
        writeln!(w, "<style type=text/css>{}</style>", VIEWER_CSS)?;
        writeln!(w, "<style type=text/css>{}</style>", VIS_CSS)?;
        writeln!(w, "<script>{}</script>", VIS_JS)?;
        writeln!(w, "<script>{}</script>", SQL_JS)?;
        writeln!(w, "<script>{}</script>", DOLL_JS)?;
        writeln!(w, "<script charset=UTF-8>{}</script>", VIEWER_JS)?;
        write_db(&mut w)?;
        writeln!(w, "</head>")?;
        writeln!(w, "<body>")?;
        writeln!(w, "<script>")?;
        writeln!(w, "const gb_conf = {}", serde_json::to_string(&self.conf)?)?;
        writeln!(
            w,
            r#"const sql_conf = {{ locateFile: filename=>"data:application/wasm;base64,{}" }};"#,
            base64::encode(SQL_WASM),
        )?;
        writeln!(w, "main(sql_conf);")?;
        writeln!(w, "</script>")?;
        writeln!(w, "</body>")?;
        writeln!(w, "</html>")?;
        Ok(())
    }
}

pub fn make_temp_file() -> io::Result<(File, PathBuf)> {
    tempfile::Builder::new()
        .prefix("glassbench-")
        .suffix(".html")
        .rand_bytes(12)
        .tempfile()?
        .keep()
        .map_err(|_| io::Error::other("temp file can't be kept"))
}

pub fn write_db<W: io::Write>(mut w: W) -> Result<(), GlassBenchError> {
    let mut file = File::open(Db::path()?)?;
    let mut bytes = Vec::new();
    file.read_to_end(&mut bytes)?;
    writeln!(
        w,
        r#"<script>const db64="{}"</script>"#,
        base64::encode(&bytes),
    )?;
    Ok(())
}
```

--------------------------------

### Initialize Graph2d with vis.js

Source: https://docs.rs/glassbench/latest/glassbench/constant.VIEWER_JS.html

Initializes a vis.Graph2d instance with specific options and a click event listener.

```javascript
(max_date-min_date)/10,
		shaded: true,
	}
	window.graph = new vis.Graph2d($("#vis"), items, groups, options)
	graph.on('click', function (properties) {
		console.log("click", properties)
	})
}
```

--------------------------------

### create_bench function

Source: https://docs.rs/glassbench/latest/src/glassbench/main_macro.rs.html

Creates a new Bench instance with a custom name and title. It is recommended to use the glassbench! macro instead of calling this directly.

```rust
pub fn create_bench<S1, S2>(name: S1, title: S2, cmd: &Command) -> Bench
where
    S1: Into<String>,
    S2: Into<String>,
{
    let mut bench = Bench::new(name, title);
    bench.tag = cmd.tag.clone();
    bench
}
```

--------------------------------

### Db::path

Source: https://docs.rs/glassbench/latest/glassbench/struct.Db.html

Returns the name of the glassbench database file.

```APIDOC
## Db::path

### Description
Returns the name of the glassbench database file.

### Method
path()

### Signature
pub fn path() -> Result<PathBuf, GlassBenchError>

### Returns
- Result<PathBuf, GlassBenchError> - The path to the database file or an error.
```

--------------------------------

### Command::read

Source: https://docs.rs/glassbench/latest/glassbench/struct.Command.html

Reads the command-line arguments from std::env::args and returns a Command instance.

```APIDOC
## Command::read

### Description
Reads the command-line arguments from std::env::args and returns a Command instance.

### Method
read

### Signature
pub fn read() -> Self

### Parameters
None

### Returns
- **Self** - A Command instance populated with the parsed arguments.

### Example
```rust
let command = Command::read();
```
```

--------------------------------

### Report::new

Source: https://docs.rs/glassbench/latest/glassbench/struct.Report.html

Creates a new Report instance with a reference to the benchmark and an optional previous benchmark for comparison.

```APIDOC
## Report::new

### Description
Creates a new Report instance with a reference to the benchmark and an optional previous benchmark for comparison.

### Method
new

### Signature
pub fn new(bench: &'b Bench, previous: &'b Option<Bench>) -> Self

### Parameters
- **bench** (&'b Bench) - Required - The benchmark to report on.
- **previous** (&'b Option<Bench>) - Required - An optional previous benchmark for comparison.

### Returns
- **Self** - A new Report instance.
```

--------------------------------

### after_bench

Source: https://docs.rs/glassbench/latest/glassbench/index.html

Prints the tabular report for the executed benchmark then graph, list history, and or save according to command.

```APIDOC
## after_bench

### Description
Prints the tabular report for the executed benchmark then graph, list history, and or save according to command.

### Usage
Call this function after running a benchmark to output results.

### Parameters
- **bench** (Bench) - Required - The benchmark that was executed.
- **command** (Command) - Required - The command specifying what to do.

### Example
```rust
after_bench(&bench, &command);
```
```

--------------------------------

### glassbench! macro

Source: https://docs.rs/glassbench

Generates a benchmark with a consistent id (using the benchmark file title), calling the benchmarking functions given in argument.

```APIDOC
## glassbench! macro

### Description
Generates a benchmark with a consistent id (using the benchmark file title), calling the benchmarking functions given in argument.

### Usage
Use the macro to define a benchmark with a title and task functions.

### Parameters
- **benchmarking functions** (function) - Required - Functions that define tasks to benchmark.

### Example
```rust
glassbench! {
    "My Benchmark",
    my_task,
}
```

```

--------------------------------

### Initialize terminal skin with make_skin

Source: https://docs.rs/glassbench/latest/src/glassbench/skin.rs.html

The make_skin function acts as a factory to return a MadSkin instance, choosing between colored or no-color styles based on the provided boolean argument.

```rust
1use termimad::{
2    crossterm::style::{Attribute::*, Color::*},
3    minimad::Alignment,
4    MadSkin,
5};
6
7/// crate the skin used for terminal display using Termimad
8pub fn make_skin(color: bool) -> MadSkin {
9    if color {
10        make_color_skin()
11    } else {
12        make_no_color_skin()
13    }
14}
15
16fn make_color_skin() -> MadSkin {
17    let mut skin = MadSkin::default();
18    //skin.paragraph.set_fg(AnsiValue(153));
19    skin.headers[0].align = Alignment::Left;
20    skin.set_headers_fg(AnsiValue(153));
21    skin.strikeout.remove_attr(CrossedOut);
22    skin.strikeout.set_fg(AnsiValue(9));
23    skin.italic.remove_attr(Italic);
24    skin.italic.set_fg(AnsiValue(70));
25    skin
26}
27
28fn make_no_color_skin() -> MadSkin {
29    MadSkin::no_style()
30}
```

--------------------------------

### TaskBench::iter

Source: https://docs.rs/glassbench

Runs the given callback repeatedly to measure its performance. This is the core method for benchmarking a specific operation.

```APIDOC
## TaskBench::iter

### Description
Runs the given callback repeatedly to measure its performance. This is the core method for benchmarking a specific operation.

### Method
function

### Parameters
- **callback** (function) - Required - The closure to benchmark.

### Example
```rust
task.iter(|| {
    // code to benchmark
});
```

```

--------------------------------

### Create UI Selectors

Source: https://docs.rs/glassbench/latest/glassbench/constant.VIEWER_JS.html

Generates dynamic UI elements for selecting benchmarks and tasks, including event handlers for updating views.

```javascript
function make_selector(bench_name, task_name) {
	let bench_name_select = $("<select.bench",
		{ change: update_task_name_select },
		gb.bench_names.map(bn => $(`<option>${bn}`))
	)
	if (bench_name) {
		let idx = gb.bench_names.indexOf(bench_name)
		if (idx >= 0) bench_name_select.selectedIndex = idx
	}
	let task_name_select = $("<select.task", { change: update_view })
	function update_task_name_select(){
		let bench_name = bench_name_select.value
		console.log('bench_name:', bench_name);
		let bench_id = gb.val("SELECT id FROM bench WHERE name=$name", { $name: bench_name })
		let task_names = gb
			.list(
				"SELECT name FROM task where bench=$bench_id",
				{ $bench_id: bench_id }
			)
		task_name_select.innerHTML = ""
		$(task_name_select, task_names.map(name => $(`<option>${name}`)))
		return task_names
	}
	let tag_input = $("<input.tag", {
		change: update_view,
		keyup: update_view,
	})
	let task_names = update_task_name_select()
	if (task_name) {
		let idx = task_names.indexOf(task_name)
		if (idx >= 0) task_name_select.selectedIndex = idx
	}
	let wrapper = $("<.selector-wrapper",
		$("<.selector",
			$("<label>bench:", bench_name_select),
			$("<label>task:", task_name_select),
			$("<select.tag-toggle", { change: update_view },
				$("<option>with tag"),
				$("<option>without tag"),
			),
			tag_input,
			$("<.legend-icon"),
			$("<button.remover>-", {
				click: () => {
					wrapper.remove()
					update_view()
				}
			})
		),
		$("<.adder",
			$("<button>+", { click: make_selector })
		)
	)
	$("#selectors", wrapper)
	update_view()
}
```

--------------------------------

### after_bench function

Source: https://docs.rs/glassbench/latest/src/glassbench/main_macro.rs.html

Prints the benchmark report and handles optional graphing, history display, and database saving. It is recommended to use the glassbench! macro instead of calling this directly.

```rust
pub fn after_bench(bench: &mut Bench, cmd: &Command) -> Result<(), GlassBenchError> {
    let printer = Printer::new();
    let mut db = Db::open()?;
    let previous = db.last_bench_named(&bench.name)?;
    let report = Report::new(bench, &previous);
    report.print(&printer);
    let mut no_save = cmd.no_save;
    if let Some(graph_arg) = cmd.graph.as_ref() {
        let task_name = bench.task_name_from_arg(graph_arg);
        let viewer = HtmlViewer::new(&bench.name, task_name);
        viewer.open_in_browser()?;
        no_save = true;
    }
    if let Some(tbl_arg) = cmd.history.as_ref() {
        let history = bench.task_history(&mut db, tbl_arg)?;
        let tbl = HistoryTbl::new(&history);
        tbl.print(&printer);
        no_save = true;
    }
    if !no_save {
        db.save_bench(bench)?;
    }
    Ok(())
}
```

--------------------------------

### HistoryTbl::new

Source: https://docs.rs/glassbench/latest/glassbench/struct.HistoryTbl.html

Creates a new HistoryTbl instance from a reference to a TaskHistory. This is the constructor for the HistoryTbl struct.

```APIDOC
## HistoryTbl::new

### Description
Creates a new HistoryTbl instance from a reference to a TaskHistory.

### Method
new

### Signature
pub fn new(history: &'b TaskHistory) -> Self

### Parameters
- **history** (&'b TaskHistory) - Required - A reference to the TaskHistory to be displayed.

### Returns
- **Self** - A new HistoryTbl instance.
```

--------------------------------

### Bench::task_name_from_arg and task_history methods

Source: https://docs.rs/glassbench/latest/src/glassbench/bench.rs.html

Methods for managing task identification and historical data retrieval. task_name_from_arg is considered unstable.

```rust
    /// Warning: this API is considered unstable
    pub fn task_name_from_arg(&self, arg: &str) -> Option<&str> {
        arg.parse::<usize>()
            .ok()
            .and_then(|num| {
                if num == 0 {
                    eprintln!("history argument 0 not yet implemented");
                    None
                } else {
                    self.tasks.get(num - 1)
                }
            })
            .map(|task| task.name.as_str())
    }

    /// load the history of a task from DB
    ///
    /// You don't have to call this yourself if you use the [glassbench!] macro.
    pub fn task_history(&self, db: &mut Db, tbl_arg: &str) -> Result<TaskHistory, GlassBenchError> {
        if let Some(task_name) = self.task_name_from_arg(tbl_arg) {
            db.task_history(&self.name, task_name)
        } else {
            Err(GlassBenchError::ClientError)
        }
    }
```

--------------------------------

### make_temp_file

Source: https://docs.rs/glassbench/latest/glassbench/fn.make_temp_file.html

Creates a temporary file and returns a tuple of the file handle and its path. This function is useful for tests or benchmarks that need a temporary file.

```APIDOC
## Function make_temp_file

### Description
Creates a temporary file and returns a tuple containing the file handle and its path.

### Signature
pub fn make_temp_file() -> Result<(File, PathBuf)>

### Parameters
None

### Returns
- Result<(File, PathBuf)> - A Result containing a tuple of the file handle and its path, or an error if creation fails.
```

--------------------------------

### TaskBench benchmarking constants and structure

Source: https://docs.rs/glassbench/latest/src/glassbench/task_bench.rs.html

Defines the configuration constants for benchmarking iterations and durations, along with the TaskBench struct used to track task measurements.

```rust
use {
    crate::*,
    std::{
        convert::TryInto,
        time::{Duration, Instant},
    },
};

/// Number of iterations to do before everything else
pub const WARMUP_ITERATIONS: usize = 2;

/// Number of iterations to do, after warmup, to estimate the total number
/// of iterations to do
///
/// (regarding real benchmark, it can be considered as part of benchmark)
pub const ESTIMATE_ITERATIONS: u32 = 5;

/// How long we'd like the measures of a task to go. Will be divided by
/// the duration of a task in the estimate phase to decide how many
/// iterations we'll do for measures
pub const OPTIMAL_DURATION_NS: u128 = Duration::from_secs(2).as_nanos();

/// The absolute minimal number of iterations we don't want to go below
/// for benchmarking (to minimize random dispersion)
pub const MINIMAL_ITERATIONS: u32 = 50;

/// Benching of one task
#[derive(Debug, Clone)]
pub struct TaskBench {
    pub name: String,
    pub measure: Option<TaskMeasure>,
}
```

--------------------------------

### GitInfo struct and methods

Source: https://docs.rs/glassbench/latest/src/glassbench/git_info.rs.html

Defines the GitInfo struct for storing commit IDs and provides methods to read the current repository state and diff two GitInfo instances.

```rust
1use git2::Repository;
2
3/// Git related information regarding the execution context
4///
5/// Right now it just contains the id of the head commit.
6#[derive(Debug, Clone)]
7pub struct GitInfo {
8    pub commit_id: String,
9}
10
11impl GitInfo {
12    /// Read the current git state (if any)
13    pub fn read() -> Option<Self> {
14        std::env::current_dir()
15            .ok()
16            .and_then(|dir| Repository::discover(dir).ok())
17            .and_then(|repo| {
18                repo.head().ok().and_then(|head| {
19                    //println!("head: {:?} {:#?} ", &head.name(), &head.kind());
20                    head.peel_to_commit().ok().map(|commit| GitInfo {
21                        commit_id: commit.id().to_string(),
22                    })
23                })
24            })
25    }
26
27    /// Build a readable abstract of the diff of two [GitInfo]
28    pub(crate) fn diff(old_gi: &Option<GitInfo>, new_gi: &Option<GitInfo>) -> String {
29        match (old_gi, new_gi) {
30            (Some(old_gi), Some(new_gi)) => {
31                if old_gi.commit_id == new_gi.commit_id {
32                    "(same commit)".to_string()
33                } else {
34                    format!(
35                        "(last commit: {})",
36                        // I'm sure there's a less stupid way to print the first 8 chars
37                        old_gi.commit_id.chars().take(8).collect::<String>(),
38                    )
39                }
40            }
41            _ => "".to_string(),
42        }
43    }
44}
```

--------------------------------

### HtmlViewer::open_in_browser

Source: https://docs.rs/glassbench/latest/glassbench/struct.HtmlViewer.html

Opens the generated HTML viewer in the default browser.

```APIDOC
## HtmlViewer::open_in_browser

### Description
Opens the generated HTML viewer in the default browser.

### Signature
pub fn open_in_browser(&self) -> Result<(), GlassBenchError>

### Parameters
- **self** (&self) - Required - The HtmlViewer instance.

### Returns
- **Result<(), GlassBenchError>** - Ok if the operation succeeds, otherwise an error.
```

--------------------------------

### Parse TaskBench from Row

Source: https://docs.rs/glassbench/latest/src/glassbench/db.rs.html

Parses a task bench record from a database row with columns: name, iterations, total_duration_ns.

```rust
fn parse_task(row: &Row<'_>) -> Result<TaskBench, rusqlite::Error> {
    let nanos: i64 = row.get(2)?;
    Ok(TaskBench {
        name: row.get(0)?,
        measure: Some(TaskMeasure {
            iterations: row.get(1)?,
            total_duration: Duration::from_nanos(nanos as u64),
        }),
    })
}
```

--------------------------------

### Report::print

Source: https://docs.rs/glassbench/latest/glassbench/struct.Report.html

Prints the report to the console. This method is typically called automatically when using the `glassbench!` macro.

```APIDOC
## Report::print

### Description
Prints the report to the console. This method is typically called automatically when using the `glassbench!` macro.

### Method
print

### Signature
pub fn print(&self, printer: &Printer)

### Parameters
- **printer** (&Printer) - Required - The printer used to output the report.

### Returns
- **()** - No return value.
```

--------------------------------

### Database Schema and Storage Interface

Source: https://docs.rs/glassbench/latest/src/glassbench/db.rs.html

Defines the SQLite schema for bench and task tables and provides the Db struct for database operations.

```rust
1use {
2    crate::*,
3    chrono::prelude::*,
4    rusqlite::{params, Connection, OptionalExtension, Row},
5    std::{path::PathBuf, time::Duration},
6};
7
8/// version of the schema
9pub const VERSION: &str = "1";
10
11fn create_tables(con: &Connection) -> Result<(), GlassBenchError> {
12    con.execute(
13        "CREATE TABLE IF NOT EXISTS bench (
14            id INTEGER PRIMARY KEY,
15            time INTEGER NOT NULL,
16            name TEXT NOT NULL,
17            title TEXT NOT NULL,
18            tag TEXT,
19            commit_id TEXT
20        )",
21        params![],
22    )?;
23    con.execute(
24        "CREATE TABLE IF NOT EXISTS task (
25            bench INTEGER NOT NULL,
26            name TEXT NOT NULL,
27            iterations INTEGER NOT NULL,
28            total_duration_ns INTEGER NOT NULL,
29            mean_duration_ns INTEGER NOT NULL,
30            FOREIGN KEY(bench) REFERENCES bench(id),
31            PRIMARY KEY(bench, name)
32        )",
33        params![],
34    )?;
35    Ok(())
36}
37
38/// Storage interface for Glassbench, wrapping a SQLite connection
39///
40/// All durations are stored as nanoseconds in i64:
41/// If the duration of a task exceeds a few centuries it can
42/// be assumed benchmarking it isn't really necessary.
43pub struct Db {
44    pub con: Connection,
45}
46
47impl Db {
48    /// return the name of the glassbench database file
49    pub fn path() -> Result<PathBuf, GlassBenchError> {
50        Ok(std::env::current_dir()?.join(format!("glassbench_v{}.db", VERSION)))
51    }
52
53    /// Create a new instance of DB, creating the sqlite file and
54    /// the tables if necessary
55    pub fn open() -> Result<Self, GlassBenchError> {
56        let con = Connection::open(Self::path()?)?;
57        create_tables(&con)?;
58        Ok(Db { con })
59    }
60
61    /// Save a bench, with included tasks if any. Return the id of the bench
62    pub fn save_bench(&mut self, bench: &Bench) -> Result<i64, GlassBenchError> {
63        self.con.execute(
64            "INSERT INTO bench (time, name, title, tag, commit_id) VALUES (?1, ?2, ?3, ?4, ?5)",
65            params![
66                bench.time.timestamp(),
67                &bench.name,
68                &bench.title,
69                &bench.tag,
70                bench.git_info.as_ref().map(|gi| &gi.commit_id),
71            ],
72        )?;
73        let bench_id = self.con.last_insert_rowid();
74        let mut ps = self.con.prepare(
75            "INSERT INTO task
76                (bench, name, iterations, total_duration_ns, mean_duration_ns)
77            VALUES (?1, ?2, ?3, ?4, ?5)",
78        )?;
79        let tasks = bench
80            .tasks
81            .iter()
82            .filter_map(|t| t.measure.as_ref().map(|mes| (&t.name, mes)));
83        for (name, mes) in tasks {
84            ps.execute(params![
85                bench_id,
86                name,
87                mes.iterations,
88                mes.total_duration.as_nanos() as i64,
89                mes.mean_duration().as_nanos() as i64,
90            ])?;
91        }
92        Ok(bench_id)
93    }
94
95    /// Load the last bench having this name
96    pub fn last_bench_named(&mut self, name: &str) -> Result<Option<Bench>, GlassBenchError> {
97        match self
98            .con
99            .query_row(
100                "SELECT id, time, name, title, tag, commit_id
101            fROM bench WHERE name=?1 ORDER BY id DESC LIMIT 1",
102                params![name],
103                parse_bench,
104            )
105            .optional()?
106        {
107            Some((bench_id, mut bench)) => {
108                let mut ps = self.con.prepare(
109                    "SELECT name, iterations, total_duration_ns FROM task WHERE bench=?1",
110                )?;
111                let iter = ps.query_map(params![bench_id], parse_task)?;
112                for task in iter {
113                    bench.tasks.push(task?);
114                }
115                Ok(Some(bench))
116            }
117            None => {
118                // no bench found
119                Ok(None)
120            }
121        }
122    }
123
124    /// Load a [TaskHistory] with all measure for a bench name and task name
125    pub fn task_history(
126        &mut self,
127        bench_name: &str,
128        task_name: &str,
129    ) -> Result<TaskHistory, GlassBenchError> {
130        let mut history = TaskHistory {
131            bench_name: bench_name.into(),
132            task_name: task_name.into(),
133            records: Vec::new(),
134        };
135        let mut ps = self.con.prepare(
136            "SELECT
137                bench.time, bench.tag, bench.commit_id,
138                task.iterations, task.total_duration_ns"
```

--------------------------------

### Command struct and read method implementation

Source: https://docs.rs/glassbench/latest/src/glassbench/command.rs.html

Defines the Command struct to store CLI flags and implements the read method to parse arguments from std::env::args. The read method handles flags like --graph, --history, --tag, --no-save, and --verbose, while filtering benchmarks.

```rust
1/// What the user asked at the cli
2#[derive(Debug, Clone)]
3pub struct Command {
4    pub benches: Vec<String>,
5    pub graph: Option<String>,
6    pub history: Option<String>,
7    pub tag: Option<String>,
8    pub no_save: bool,
9    pub verbose: bool,
10}
11
12impl Command {
13    /// read std::env::args
14    pub fn read() -> Self {
15        let mut args = std::env::args().skip(1); // it's the path to the compiled bench in target
16        let mut benches = Vec::new();
17        let mut graph = None;
18        let mut history = None;
19        let mut tag = None;
20        let mut before_sep = true;
21        let mut no_save = false;
22        let mut verbose = false;
23        while let Some(arg) = args.next() {
24            if arg == "--" {
25                before_sep = false;
26            } else if before_sep {
27                if !arg.starts_with("--") {
28                    benches.push(arg);
29                }
30            } else {
31                match arg.as_str() {
32                    "--no-save" => {
33                        no_save = true;
34                    }
35                    "--verbose" => {
36                        verbose = true;
37                    }
38                    "--graph" => {
39                        if let Some(val) = args.next() {
40                            graph = Some(val);
41                        }
42                    }
43                    "--history" => {
44                        if let Some(val) = args.next() {
45                            history = Some(val);
46                        }
47                    }
48                    "--tag" => {
49                        if let Some(val) = args.next() {
50                            tag = Some(val);
51                        }
52                    }
53                    "--bench" => {
54                        // that's how the command given by cargo bench always ends
55                    }
56                    _ => {
57                        println!("ignored bench argument: {:?}", arg);
58                    }
59                }
60            }
61        }
62        Self {
63            benches,
64            graph,
65            history,
66            tag,
67            no_save,
68            verbose,
69        }
70    }
71
72    /// tell whether this specific bench should be included
73    pub fn include_bench(&self, name: &str) -> bool {
74        self.benches.is_empty() || self.benches.iter().any(|g| g == name)
75    }
76}
```

--------------------------------

### Db::task_history

Source: https://docs.rs/glassbench/latest/glassbench/struct.Db.html

Loads a TaskHistory with all measures for a bench name and task name.

```APIDOC
## Db::task_history

### Description
Loads a TaskHistory with all measures for a bench name and task name.

### Method
task_history(&mut self, bench_name: &str, task_name: &str)

### Signature
pub fn task_history(&mut self, bench_name: &str, task_name: &str) -> Result<TaskHistory, GlassBenchError>

### Parameters
- bench_name: &str - The name of the bench.
- task_name: &str - The name of the task.

### Returns
- Result<TaskHistory, GlassBenchError> - The task history or an error.
```

--------------------------------

### HistoryGraph::new

Source: https://docs.rs/glassbench/latest/glassbench/struct.HistoryGraph.html

Creates a new HistoryGraph instance from a reference to a TaskHistory. This is the constructor for the HistoryGraph struct.

```APIDOC
## HistoryGraph::new

### Description
Creates a new HistoryGraph instance from a reference to a TaskHistory.

### Method
Constructor

### Signature
pub fn new(history: &'b TaskHistory) -> Self

### Parameters
- **history** (&'b TaskHistory) - Required - A reference to the task history to graph.

### Returns
- **Self** - A new HistoryGraph instance.
```

--------------------------------

### Parse Bench from Row

Source: https://docs.rs/glassbench/latest/src/glassbench/db.rs.html

Parses a bench record from a database row with columns: id, time, name, title, tag, commit_id.

```rust
fn parse_bench(row: &Row<'_>) -> Result<(i64, Bench), rusqlite::Error> {
    let bench_id: i64 = row.get(0)?;
    let commit_id: Option<String> = row.get(5)?;
    let secs: i64 = row.get(1)?;
    let bench = Bench {
        time: DateTime::from_timestamp(secs, 0)
            .ok_or(rusqlite::Error::IntegralValueOutOfRange(1, secs))?,
        name: row.get(2)?,
        title: row.get(3)?,
        tag: row.get(4)?,
        git_info: commit_id.map(|commit_id| GitInfo { commit_id }),
        tasks: Vec::new(),
    };
    Ok((bench_id, bench))
}
```

--------------------------------

### glassbench! macro definition

Source: https://docs.rs/glassbench/latest/src/glassbench/main_macro.rs.html

The implementation of the glassbench! macro which generates a main function that reads command arguments and executes the provided benchmark functions.

```rust
macro_rules! glassbench {
    (
        $title: literal,
        $( $fun: path, )+
    ) => {
        pub fn main() {
            use glassbench::*;
            let name = env!("CARGO_CRATE_NAME");
            let cmd = Command::read();
            if cmd.include_bench(&name) {
                let mut bench = create_bench(name, $title, &cmd);
                $(
                    $fun(&mut bench);
                )+
                if let Err(e) = after_bench(&mut bench, &cmd) {
                    eprintln!("{}", e);
                }
            } else {
                println!("skipping bench {:?}", &name);
            }
        }
    }
}
```

--------------------------------

### Bench::task_history

Source: https://docs.rs/glassbench/latest/glassbench/struct.Bench.html

Loads the history of a task from the database. This method is typically not called directly if using the glassbench! macro.

```APIDOC
## Bench::task_history

### Description
Loads the history of a task from the database. This method is typically not called directly if using the glassbench! macro.

### Method
task_history

### Signature
pub fn task_history(&self, db: &mut Db, tbl_arg: &str) -> Result<TaskHistory, GlassBenchError>

### Parameters
- **db** (&mut Db) - Required - A mutable reference to the database.
- **tbl_arg** (&str) - Required - The table argument specifying which task history to load.

### Returns
- **Result<TaskHistory, GlassBenchError>** - The task history on success, or an error.

```

--------------------------------

### Wrap Database Interface

Source: https://docs.rs/glassbench/latest/glassbench/constant.VIEWER_JS.html

Wraps a database object to provide simplified query methods for values and lists.

```javascript
function wrap(db) {
	let gb = {}
	gb.val = (sql, args) => gb.list(sql, args)[0]
	gb.list = (sql, args) => {
		let res = db.exec(sql, args)[0]
		return res ? res.values.map(r => r[0]) : []
	}
	gb.lists = (sql, args) => {
		let res = db.exec(sql, args)[0]
		return res ? res.values : []
	}
	gb.bench_names = gb.list("SELECT DISTINCT(name) FROM bench")
	return gb
}
```

--------------------------------

### Implement pretend_used for benchmarking

Source: https://docs.rs/glassbench/latest/src/glassbench/black_box.rs.html

Uses a volatile read to prevent the compiler from optimizing away the provided argument. This serves as a temporary implementation until core::hint::bench_black_box is stabilized.

```rust
pub fn pretend_used<T>(t: T) -> T {
    unsafe {
        let ret = std::ptr::read_volatile(&t);
        std::mem::forget(t);
        ret
    }
}
```

--------------------------------

### Command::include_bench

Source: https://docs.rs/glassbench/latest/glassbench/struct.Command.html

Determines whether a specific bench should be included based on the command's bench list.

```APIDOC
## Command::include_bench

### Description
Determines whether a specific bench should be included based on the command's bench list.

### Method
include_bench

### Signature
pub fn include_bench(&self, name: &str) -> bool

### Parameters
- **name** (&str) - The name of the bench to check.

### Returns
- **bool** - true if the bench should be included, false otherwise.

### Example
```rust
let command = Command::read();
if command.include_bench("my_bench") {
    // run bench
}
```
```

--------------------------------

### TaskBench::iter

Source: https://docs.rs/glassbench/latest/index.html

Calls the callback to benchmark. The TaskBench struct is received as an argument when defining a task.

```APIDOC
## TaskBench::iter

### Description
Calls the callback to benchmark. The TaskBench struct is received as an argument when defining a task.

### Method
`iter`

### Parameters
- **callback** (function) - Required - The callback to benchmark.

### Example
```rust
task.iter(|| {
    // code to benchmark
});
```
```

--------------------------------

### Define TaskRecord and TaskHistory structures

Source: https://docs.rs/glassbench/latest/src/glassbench/task_history.rs.html

Defines the TaskRecord struct for individual task measurements and the TaskHistory struct for aggregating records by bench and task name.

```rust
1use {crate::*, chrono::prelude::*};
2
3/// A measure of a task, with time, commit and tag
4#[derive(Debug)]
5pub struct TaskRecord {
6    pub time: DateTime<Utc>,
7    pub git_info: Option<GitInfo>,
8    pub tag: Option<String>,
9    pub measure: TaskMeasure,
10}
11
12/// The history of the measures of ta task as defined
13/// by the bench name and task name
14#[derive(Debug)]
15pub struct TaskHistory {
16    pub bench_name: String,
17    pub task_name: String,
18    pub records: Vec<TaskRecord>,
19}
```

--------------------------------

### write_db

Source: https://docs.rs/glassbench/latest/glassbench/fn.write_db.html

Writes a database to the provided writer. Returns a Result indicating success or a GlassBenchError.

```APIDOC
## write_db

### Description
Writes a database to the provided writer. Returns a Result indicating success or a GlassBenchError.

### Function Signature
pub fn write_db<W: Write>(w: W) -> Result<(), GlassBenchError>

### Parameters
- **w** (W) - Required - A writer that implements the Write trait.

### Return Value
- **Result<(), GlassBenchError>** - Ok(()) on success, or an error of type GlassBenchError.
```