Benchmark

A minimal microbenchmarking framework. More...

Classes
class	sourcemeta::core::BenchmarkState

Functions
SOURCEMETA_CORE_BENCHMARK_EXPORT auto	sourcemeta::core::benchmark_use_char_pointer (const volatile char *pointer) -> void
template<typename Type>
SOURCEMETA_FORCEINLINE auto	sourcemeta::core::benchmark_do_not_optimize (Type &value) -> void
template<typename Type>
SOURCEMETA_FORCEINLINE auto	sourcemeta::core::benchmark_do_not_optimize (const Type &value) -> void
SOURCEMETA_CORE_BENCHMARK_EXPORT auto	sourcemeta::core::benchmark_register (std::string_view name, std::string_view file, int line, std::function< void(BenchmarkState &)> body) -> int
SOURCEMETA_CORE_BENCHMARK_EXPORT auto	sourcemeta::core::benchmark_run (int argc, char **argv) -> int

Detailed Description

A minimal microbenchmarking framework.

This functionality is included as follows:

#include <sourcemeta/core/benchmark.h>

---

Class Documentation

sourcemeta::core::BenchmarkState

class sourcemeta::core::BenchmarkState

The state of one benchmark run, i.e. how many iterations to perform and the time they took. A benchmark body obtains it from the registration macro and consumes it by iterating over it.

Public Member Functions
	BenchmarkState (const std::uint64_t iterations)
	Prepare a run of the given number of iterations.
auto	iterations () const -> std::uint64_t
	How many iterations this run was asked to perform.
auto	measured () const -> bool
	Whether the body actually iterated.
auto	real_time () const -> std::chrono::nanoseconds
	How long the iterations took on the clock.
auto	cpu_time () const -> std::optional< std::chrono::nanoseconds >

Member Function Documentation

cpu_time()

auto sourcemeta::core::BenchmarkState::cpu_time ( ) const -> std::optional< std::chrono::nanoseconds >

nodiscard

How much processor time the iterations consumed, where the platform can answer.

Function Documentation

benchmark_do_not_optimize() [1/2]

template<typename Type>

SOURCEMETA_FORCEINLINE auto sourcemeta::core::benchmark_do_not_optimize ( const Type & value ) -> void

inline

Keep a value the compiler would otherwise discard, where the caller holds it by constant reference or produced it as a temporary. For example:

#include <sourcemeta/core/benchmark.h>
 
BENCHMARK(Addition) {
  const auto left{1};
  for (auto iteration : state) {
    sourcemeta::core::benchmark_do_not_optimize(left + 1);
  }
}

benchmark_do_not_optimize() [2/2]

template<typename Type>

SOURCEMETA_FORCEINLINE auto sourcemeta::core::benchmark_do_not_optimize ( Type & value ) -> void

inline

Keep a value the compiler would otherwise discard. For example:

#include <sourcemeta/core/benchmark.h>
 
BENCHMARK(Addition) {
  for (auto iteration : state) {
    auto result{1 + 1};
    sourcemeta::core::benchmark_do_not_optimize(result);
  }
}

benchmark_register()

SOURCEMETA_CORE_BENCHMARK_EXPORT auto sourcemeta::core::benchmark_register	(	std::string_view	name,
		std::string_view	file,
		int	line,
		std::function< void(BenchmarkState &)>	body ) -> int

Register a benchmark by name with a callable body. Returns a dummy value so it can be used to initialise a namespace-scope variable.

benchmark_run()

SOURCEMETA_CORE_BENCHMARK_EXPORT auto sourcemeta::core::benchmark_run	(	int	argc,
		char **	argv ) -> int

Run every registered benchmark, optionally filtered, and return a process exit code.

benchmark_use_char_pointer()

SOURCEMETA_CORE_BENCHMARK_EXPORT auto sourcemeta::core::benchmark_use_char_pointer

(

const volatile char *

pointer

)

-> void

Consume a pointer without looking at it. Only the platforms that offer no inline assembly rely on this.