Add idea of a benchmark title

This adds a configuration option for a `title` key, and also prints the
title in the console formatter if set.

lib/benchee/configuration.ex

@@ -41,7 +41,8 @@ defmodule Benchee.Configuration do
             after_each: nil,
             before_scenario: nil,
             after_scenario: nil,
-            measure_function_call_overhead: true
+            measure_function_call_overhead: true,
+            title: nil
 
   @type t :: %__MODULE__{
           parallel: integer,
@@ -61,7 +62,8 @@ defmodule Benchee.Configuration do
           after_each: fun | nil,
           before_scenario: fun | nil,
           after_scenario: fun | nil,
-          measure_function_call_overhead: boolean
+          measure_function_call_overhead: boolean,
+          title: String.t() | nil
         }
 
   @type user_configuration :: map | keyword
@@ -89,6 +91,9 @@ defmodule Benchee.Configuration do
     to work your benchmarking function gets the current input passed in as an
     argument into the function. Defaults to `nil`, aka no input specified and
     functions are called without an argument.
+    * `title` - this option is purely cosmetic. If you would like to add a
+    title with some meaning to a given suite, you can do so by providing
+    a single string here. This is only for use by formatters.
     * `formatters` - list of formatters either as module implementing the
     formatter behaviour or formatter functions. They are run when using
     `Benchee.run/2`. Functions need to accept one argument (which is the

lib/benchee/formatters/console.ex

@@ -86,11 +86,15 @@ defmodule Benchee.Formatters.Console do
   defp console_configuration(config) do
     %Configuration{
       formatter_options: %{console: console_config},
-      unit_scaling: scaling_strategy
+      unit_scaling: scaling_strategy,
+      title: title
     } = config
 
     if Map.has_key?(console_config, :unit_scaling), do: warn_unit_scaling()
-    Map.put(console_config, :unit_scaling, scaling_strategy)
+
+    console_config
+    |> Map.put(:unit_scaling, scaling_strategy)
+    |> Map.put(:title, title)
   end
 
   defp warn_unit_scaling do
@@ -101,11 +105,18 @@ defmodule Benchee.Formatters.Console do
 
   defp generate_output(scenarios, config, input) do
     [
-      input_header(input)
+      suite_header(input, config)
       | RunTime.format_scenarios(scenarios, config) ++ Memory.format_scenarios(scenarios, config)
     ]
   end
 
+  defp suite_header(input, config) do
+    "#{title_header(config)}#{input_header(input)}"
+  end
+
+  defp title_header(%{title: nil}), do: ""
+  defp title_header(%{title: title}), do: "\n*** #{title} ***\n"
+
   @no_input_marker Benchee.Benchmark.no_input()
   defp input_header(input) when input == @no_input_marker, do: ""
   defp input_header(input), do: "\n##### With input #{input} #####"

samples/title.exs

@@ -0,0 +1,37 @@
+list = Enum.to_list(1..10_000)
+map_fun = fn(i) -> [i, i * i] end
+
+Benchee.run(%{
+  "flat_map"    => fn -> Enum.flat_map(list, map_fun) end,
+  "map.flatten" => fn -> list |> Enum.map(map_fun) |> List.flatten end
+}, time: 2, title: "Comparing map.flatten and flat_map")
+
+# $ mix run samples/title.exs
+# Operating System: macOS"
+# CPU Information: Intel(R) Core(TM) i5-4260U CPU @ 1.40GHz
+# Number of Available Cores: 4
+# Available memory: 8 GB
+# Elixir 1.6.4
+# Erlang 20.3
+
+# Benchmark suite executing with the following configuration:
+# warmup: 2 s
+# time: 2 s
+# memory time: 0 ns
+# parallel: 1
+# inputs: none specified
+# Estimated total run time: 8 s
+
+
+# Benchmarking flat_map...
+# Benchmarking map.flatten...
+
+# *** Comparing map.flatten and flat_map ***
+
+# Name                  ips        average  deviation         median         99th %
+# flat_map           1.09 K        0.92 ms    ±34.81%        0.78 ms        1.96 ms
+# map.flatten        0.61 K        1.65 ms    ±26.90%        1.45 ms        2.72 ms
+
+# Comparison:
+# flat_map           1.09 K
+# map.flatten        0.61 K - 1.80x slower

test/benchee/formatters/console_test.exs

@@ -11,7 +11,8 @@ defmodule Benchee.Formatters.ConsoleTest do
         comparison: true,
         extended_statistics: false
       }
-    }
+    },
+    title: "A comprehensive benchmarking of inputs"
   }
   @no_input Benchee.Benchmark.no_input()
 
@@ -227,5 +228,28 @@ defmodule Benchee.Formatters.ConsoleTest do
       assert job =~ ~r/job\s+5 K/
       assert comparison =~ ~r/job \(improved\)\s+ 10 K/
     end
+
+    test "includes the suite's title" do
+      scenarios = [
+        %Scenario{
+          name: "job",
+          input_name: @no_input,
+          input: @no_input,
+          run_time_statistics: %Statistics{
+            average: 200.0,
+            ips: 5_000.0,
+            std_dev_ratio: 0.1,
+            median: 195.5,
+            percentiles: %{99 => 300.1},
+            sample_size: 200
+          },
+          memory_usage_statistics: %Statistics{}
+        }
+      ]
+
+      [[title | _]] = Console.format(%Suite{scenarios: scenarios, configuration: @config})
+
+      assert title =~ ~r/A comprehensive benchmarking of inputs/
+    end
   end
 end