SnakeBridge.Benchmark (SnakeBridge v0.16.0)

Copy Markdown View Source

Benchmark utilities for SnakeBridge performance measurement.

Provides functions for measuring execution time, collecting statistics, and comparing performance across different configurations.

Usage

# Single measurement
result = Benchmark.measure("my_operation", fn -> do_work() end)

# Multiple iterations with statistics
stats = Benchmark.run_iterations("my_operation", fn -> do_work() end, 10)

# Compare two runs
comparison = Benchmark.compare(baseline_stats, current_stats)

Summary

Types

comparison()
measurement()
stats()

Functions

compare(map1, map2)

Compares two benchmark results and calculates improvement metrics.

format_bytes(bytes)

Formats a byte count to a human-readable string.

format_time(us)

Formats a time in microseconds to a human-readable string.

measure(name, fun)

Measures the execution time of a single function call.

print_comparison(comparison)

Prints a comparison between two benchmark runs.

print_stats(stats)

Prints a summary of benchmark statistics.

run_iterations(name, fun, iterations \\ 10)

Runs a function multiple times and collects statistics.

Types

comparison()

@type comparison() :: %{
  speedup: float(),
  improvement_percent: float(),
  baseline_mean_us: float(),
  current_mean_us: float()
}

measurement()

@type measurement() :: %{
  name: String.t(),
  time_us: non_neg_integer(),
  value: term(),
  error: String.t() | nil
}

stats()

@type stats() :: %{
  name: String.t(),
  iterations: non_neg_integer(),
  mean_us: float(),
  median_us: float(),
  min_us: non_neg_integer(),
  max_us: non_neg_integer(),
  std_dev_us: float(),
  times_us: [non_neg_integer()]
}

Functions

compare(map1, map2)

@spec compare(map(), map()) :: comparison()

Compares two benchmark results and calculates improvement metrics.

Returns:

  • speedup - Ratio (> 1.0 means faster)
  • improvement_percent - Percentage improvement (positive is faster)

format_bytes(bytes)

@spec format_bytes(number()) :: String.t()

Formats a byte count to a human-readable string.

Examples

iex> Benchmark.format_bytes(1024)
"1.00 KB"

iex> Benchmark.format_bytes(1_048_576)
"1.00 MB"

format_time(us)

@spec format_time(number()) :: String.t()

Formats a time in microseconds to a human-readable string.

Examples

iex> Benchmark.format_time(500)
"500 µs"

iex> Benchmark.format_time(5_000)
"5.00 ms"

iex> Benchmark.format_time(5_000_000)
"5.00 s"

measure(name, fun)

@spec measure(String.t(), (-> term())) :: measurement()

Measures the execution time of a single function call.

Returns a map with:

  • name - The benchmark name
  • time_us - Execution time in microseconds
  • value - The function's return value
  • error - Error message if the function raised

run_iterations(name, fun, iterations \\ 10)

@spec run_iterations(String.t(), (-> term()), non_neg_integer()) :: stats()

Runs a function multiple times and collects statistics.

Returns a map with statistical measures:

  • mean_us - Average time in microseconds
  • median_us - Median time in microseconds
  • min_us - Minimum time
  • max_us - Maximum time
  • std_dev_us - Standard deviation