Add support for custom information per benchmark run

src/docs/tutorial.rst

@@ -342,6 +342,11 @@ output:
  :language: c++
  :linenos:
 
+Nanobench allows to specify further context information, which may be accessed using ``{{context(name)}}`` where ``name`` names a variable defined in ``Bench::context()``.
+
+.. literalinclude:: ../test/tutorial_context.cpp
+ :language: c++
+ :linenos:
 
 .. _tutorial-template-csv:
 

src/include/nanobench.h

@@ -43,6 +43,7 @@
 #include <cstring> // memcpy
 #include <iosfwd> // for std::ostream* custom output target in Config
 #include <string> // all names
+#include <unordered_map> // holds context information of results
 #include <vector> // holds all results
 
 #define ANKERL_NANOBENCH(x) ANKERL_NANOBENCH_PRIVATE_##x()
@@ -177,6 +178,8 @@ class BigO;
  *
  * * `{{relative}}` True or false, depending on the setting you have used. See Bench::relative().
  *
+ * * `{{context(variableName)}} See Bench::context().
+ *
  * Apart from these tags, it is also possible to use some mathematical operations on the measurement data. The operations
  * are of the form `{{command(name)}}`. Currently `name` can be one of `elapsed`, `iterations`. If performance counters
  * are available (currently only on current Linux systems), you also have `pagefaults`, `cpucycles`,
@@ -395,6 +398,7 @@ struct Config {
  std::string mTimeUnitName = "ns";
  bool mShowPerformanceCounters = true;
  bool mIsRelative = false;
+ std::unordered_map<std::string,std::string> mContext{};
 
  Config();
  ~Config();
@@ -442,6 +446,7 @@ class Result {
  ANKERL_NANOBENCH(NODISCARD) double sumProduct(Measure m1, Measure m2) const noexcept;
  ANKERL_NANOBENCH(NODISCARD) double minimum(Measure m) const noexcept;
  ANKERL_NANOBENCH(NODISCARD) double maximum(Measure m) const noexcept;
+ ANKERL_NANOBENCH(NODISCARD) std::string const& context(std::string const&) const noexcept;
 
  ANKERL_NANOBENCH(NODISCARD) bool has(Measure m) const noexcept;
  ANKERL_NANOBENCH(NODISCARD) double get(size_t idx, Measure m) const;
@@ -674,6 +679,20 @@ class Bench {
  Bench& name(std::string const& benchmarkName);
  ANKERL_NANOBENCH(NODISCARD) std::string const& name() const noexcept;
 
+ /**
+ * @brief Set context information.
+ *
+ * The information can be accessed using custom render templates via `{{context(variableName)}}`.
+ * Trying to render a variable that hasn't been set before, results in empty output (for that variable).
+ * Not included in (default) markdown table.
+ *
+ * @see render()
+ *
+ * @param variableName The name of the context variable.
+ * @param variableValue The value of the context variable.
+ */
+ Bench& context(std::string const& variableName, std::string const& variableValue);
+
  /**
  * @brief Sets the batch size.
  *
@@ -1600,6 +1619,10 @@ static std::ostream& generateResultTag(Node const& n, Result const& r, std::ostr
  std::vector<std::string> matchResult;
  if (matchCmdArgs(std::string(n.begin, n.end), matchResult)) {
  if (matchResult.size() == 2) {
+ if (matchResult[0] == "context") {
+ return out << r.context(matchResult[1]);
+ }
+
  auto m = Result::fromString(matchResult[1]);
  if (m == Result::Measure::_size) {
  return out << 0.0;
@@ -2991,6 +3014,16 @@ double Result::maximum(Measure m) const noexcept {
  return *std::max_element(data.begin(), data.end());
 }
 
+std::string const& Result::context(std::string const& variableName) const noexcept {
+ auto context = mConfig.mContext;
+ auto search = context.find(variableName);
+ static std::string NOTFOUND;
+ if (search == context.end()) {
+ return NOTFOUND;
+ }
+ return search->second;
+}
+
 Result::Measure Result::fromString(std::string const& str) {
  if (str == "elapsed") {
  return Measure::elapsed;
@@ -3118,6 +3151,11 @@ std::string const& Bench::name() const noexcept {
  return mConfig.mBenchmarkName;
 }
 
+Bench& Bench::context(std::string const& variableName, std::string const& variableValue) {
+ mConfig.mContext[variableName] = variableValue;
+ return *this;
+}
+
 // Number of epochs to evaluate. The reported result will be the median of evaluation of each epoch.
 Bench& Bench::epochs(size_t numEpochs) noexcept {
  mConfig.mNumEpochs = numEpochs;

src/test/CMakeLists.txt

@@ -19,6 +19,7 @@ target_sources_local(nb PRIVATE
  example_shuffle.cpp
  tutorial_complexity_set.cpp
  tutorial_complexity_sort.cpp
+ tutorial_context.cpp
  tutorial_fast_v1.cpp
  tutorial_fast_v2.cpp
  tutorial_fluctuating_v1.cpp

src/test/tutorial_context.cpp

@@ -0,0 +1,50 @@
+#include <nanobench.h>
+#include <thirdparty/doctest/doctest.h>
+
+#include <iostream>
+#include <cmath>
+
+namespace {
+
+template<typename T>
+void fma() {
+ T x(1), y(2), z(3);
+ z = std::fma(x, y, z);
+ ankerl::nanobench::doNotOptimizeAway(z);
+}
+
+template<typename T>
+void plus_eq() {
+ T x(1), y(2), z(3);
+ z += x*y;
+ ankerl::nanobench::doNotOptimizeAway(z);
+}
+
+char const* csv() {
+ return R"DELIM("title";"name";"scalar";"foo";"elapsed";"total"
+{{#result}}"{{title}}";"{{name}}";"{{context(scalar)}}";"{{context(foo)}}";{{median(elapsed)}};{{sumProduct(iterations, elapsed)}}
+{{/result}})DELIM";
+}
+
+} // namespace
+
+TEST_CASE("tutorial_context") {
+ ankerl::nanobench::Bench bench;
+ bench.title("Addition").output(nullptr);
+ bench.run("missing context", [] {
+ int a = 1, b = 2;
+ int c = a + b;
+ ankerl::nanobench::doNotOptimizeAway(c);
+ });
+ bench
+ .context("scalar", "f32")
+ .context("foo", "bar")
+ .run("+=", plus_eq<float>)
+ .run("fma", fma<float>);
+ bench
+ .context("scalar", "f64")
+ .context("foo", "baz")
+ .run("+=", plus_eq<double>)
+ .run("fma", fma<double>);
+ bench.render(csv(), std::cout);
+}