Make unit_scaling a top level configuration option

fixes #58
bencheeorg · Oct 7, 2017 · 224fc84 · 224fc84
1 parent 83ddcee
commit 224fc84
Show file tree

Hide file tree

Showing 6 changed files with 70 additions and 47 deletions.
diff --git a/README.md b/README.md
@@ -146,20 +146,23 @@ The available options are the following (also documented in [hexdocs](https://he
   * `:fast_warning` - warnings are displayed if functions are executed too fast leading to inaccurate measures
 * `console` - options for the built-in console formatter. Like the `print` options they are also enabled by default:
   * `:comparison` - if the comparison of the different benchmarking jobs (x times slower than) is shown
-  * `:unit_scaling` - the strategy for choosing a unit for durations and
-  counts. When scaling a value, Benchee finds the "best fit" unit (the
-  largest unit for which the result is at least 1). For example, 1_200_000
-  scales to `1.2 M`, while `800_000` scales to `800 K`. The `unit_scaling`
-  strategy determines how Benchee chooses the best fit unit for an entire
-  list of values, when the individual values in the list may have different
-  best fit units. There are four strategies, defaulting to `:best`:
-    * `:best`    - the most frequent best fit unit will be used, a tie will
-    result in the larger unit being selected.
+* `:unit_scaling` - the strategy for choosing a unit for durations and
+  counts. May or may not be implemented by a given formatter (The console
+  formatter implements it). When scaling a value, Benchee finds the "best fit"
+  unit (the largest unit for which the result is at least 1). For example,
+  1_200_000 scales to `1.2 M`, while `800_000` scales to `800 K`. The
+  `unit_scaling` strategy determines how Benchee chooses the best fit unit for
+  an entire list of values, when the individual values in the list may have
+  different best fit units. There are four strategies, defaulting to `:best`:
+    * `:best`     - the most frequent best fit unit will be used, a tie
+    will result in the larger unit being selected.
     * `:largest`  - the largest best fit unit will be used (i.e. thousand
-    and seconds if values are large enough)
-    * `:smallest` - the smallest best fit unit will be used (i.e. millisecond
-    and one)
-    * `:none`     - no unit scaling will occur. Durations will be displayed in microseconds, and counts will be displayed in ones (this is equivalent to the behaviour Benchee had pre 0.5.0)
+    and seconds if values are large enough).
+    * `:smallest` - the smallest best fit unit will be used (i.e.
+    millisecond and one)
+    * `:none`     - no unit scaling will occur. Durations will be displayed
+    in microseconds, and counts will be displayed in ones (this is
+    equivalent to the behaviour Benchee had pre 0.5.0)
 
 ### Inputs
 

diff --git a/lib/benchee/configuration.ex b/lib/benchee/configuration.ex
@@ -7,6 +7,7 @@ defmodule Benchee.Configuration do
     Suite,
     Configuration,
     Conversion.Duration,
+    Conversion.Scale,
     Utility.DeepConvert,
     Formatters.Console
   }
@@ -26,10 +27,10 @@ defmodule Benchee.Configuration do
     # the top level for now
     formatter_options: %{
       console: %{
-        comparison:    true,
-        unit_scaling:  :best
+        comparison:    true
       }
     },
+    unit_scaling:     :best,
     # If you/your plugin/whatever needs it your data can go here
     assigns:           %{},
     before_each:       nil,
@@ -46,6 +47,7 @@ defmodule Benchee.Configuration do
     print:             map,
     inputs:            %{Suite.key => any} | nil,
     formatter_options: map,
+    unit_scaling:      Scale.best_unit_strategy,
     assigns:           map,
     before_each:       fun | nil,
     after_each:        fun | nil,
@@ -101,22 +103,23 @@ defmodule Benchee.Configuration do
     `print` options the boolean options are also enabled by default:
       * `:comparison`   - if the comparison of the different benchmarking jobs
       (x times slower than) is shown (true/false)
-      * `:unit_scaling` - the strategy for choosing a unit for durations and
-      counts. When scaling a value, Benchee finds the "best fit" unit (the
-      largest unit for which the result is at least 1). For example, 1_200_000
-      scales to `1.2 M`, while `800_000` scales to `800 K`. The `unit_scaling`
-      strategy determines how Benchee chooses the best fit unit for an entire
-      list of values, when the individual values in the list may have different
-      best fit units. There are four strategies, defaulting to `:best`:
-          * `:best`     - the most frequent best fit unit will be used, a tie
-          will result in the larger unit being selected.
-          * `:largest`  - the largest best fit unit will be used (i.e. thousand
-          and seconds if values are large enough).
-          * `:smallest` - the smallest best fit unit will be used (i.e.
-          millisecond and one)
-          * `:none`     - no unit scaling will occur. Durations will be displayed
-          in microseconds, and counts will be displayed in ones (this is
-          equivalent to the behaviour Benchee had pre 0.5.0)
+    * `:unit_scaling` - the strategy for choosing a unit for durations and
+    counts. May or may not be implemented by a given formatter (The console
+    formatter implements it). When scaling a value, Benchee finds the "best fit"
+    unit (the largest unit for which the result is at least 1). For example,
+    1_200_000 scales to `1.2 M`, while `800_000` scales to `800 K`. The
+    `unit_scaling` strategy determines how Benchee chooses the best fit unit for
+    an entire list of values, when the individual values in the list may have
+    different best fit units. There are four strategies, defaulting to `:best`:
+      * `:best`     - the most frequent best fit unit will be used, a tie
+      will result in the larger unit being selected.
+      * `:largest`  - the largest best fit unit will be used (i.e. thousand
+      and seconds if values are large enough).
+      * `:smallest` - the smallest best fit unit will be used (i.e.
+      millisecond and one)
+      * `:none`     - no unit scaling will occur. Durations will be displayed
+      in microseconds, and counts will be displayed in ones (this is
+      equivalent to the behaviour Benchee had pre 0.5.0)
 
   ## Examples
 
@@ -135,8 +138,9 @@ defmodule Benchee.Configuration do
               configuration: true
             },
             formatter_options: %{
-              console: %{ comparison: true, unit_scaling: :best }
+              console: %{comparison: true}
             },
+            unit_scaling: :best,
             assigns: %{},
             before_each: nil,
             after_each: nil,
@@ -162,8 +166,9 @@ defmodule Benchee.Configuration do
               configuration: true
             },
             formatter_options: %{
-              console: %{ comparison: true, unit_scaling: :best }
+              console: %{comparison: true}
             },
+            unit_scaling: :best,
             assigns: %{},
             before_each: nil,
             after_each: nil,
@@ -189,8 +194,9 @@ defmodule Benchee.Configuration do
               configuration: true
             },
             formatter_options: %{
-              console: %{ comparison: true, unit_scaling: :best }
+              console: %{comparison: true}
             },
+            unit_scaling: :best,
             assigns: %{},
             before_each: nil,
             after_each: nil,
@@ -207,9 +213,10 @@ defmodule Benchee.Configuration do
       ...>   warmup: 0.2,
       ...>   formatters: [&IO.puts/2],
       ...>   print: [fast_warning: false],
-      ...>   console: [unit_scaling: :smallest],
+      ...>   console: [comparison: false],
       ...>   inputs: %{"Small" => 5, "Big" => 9999},
-      ...>   formatter_options: [some: "option"])
+      ...>   formatter_options: [some: "option"],
+      ...>   unit_scaling: :smallest)
       %Benchee.Suite{
         configuration:
           %Benchee.Configuration{
@@ -224,9 +231,10 @@ defmodule Benchee.Configuration do
               configuration: true
             },
             formatter_options: %{
-              console: %{ comparison: true, unit_scaling: :smallest },
+              console: %{comparison: false},
               some: "option"
             },
+            unit_scaling: :smallest,
             assigns: %{},
             before_each: nil,
             after_each: nil,

diff --git a/lib/benchee/conversion/scale.ex b/lib/benchee/conversion/scale.ex
@@ -12,6 +12,7 @@ defmodule Benchee.Conversion.Scale do
   @type unit_atom :: atom
   @type any_unit :: unit | unit_atom
   @type scaled_number :: {number, unit}
+  @type best_unit_strategy :: :best | :largest | :smallest | :none
 
   @doc """
   Scales a number in a domain's base unit to an equivalent value in the best

diff --git a/lib/benchee/formatters/console.ex b/lib/benchee/formatters/console.ex
@@ -6,7 +6,7 @@ defmodule Benchee.Formatters.Console do
 
   @behaviour Benchee.Formatter
 
-  alias Benchee.{Statistics, Suite, Benchmark.Scenario}
+  alias Benchee.{Statistics, Suite, Benchmark.Scenario, Configuration}
   alias Benchee.Conversion.{Count, Duration, Unit, DeviationPercent}
 
   @type unit_per_statistic :: %{atom => Unit.t}
@@ -56,8 +56,9 @@ defmodule Benchee.Formatters.Console do
   ...>   scenarios: scenarios,
   ...>   configuration: %Benchee.Configuration{
   ...>     formatter_options: %{
-  ...>       console: %{comparison: false, unit_scaling: :best}
-  ...>     }
+  ...>       console: %{comparison: false}
+  ...>     },
+  ...>     unit_scaling: :best
   ...>   }
   ...> }
   iex> Benchee.Formatters.Console.format(suite)
@@ -69,8 +70,8 @@ defmodule Benchee.Formatters.Console do
 
   """
   @spec format(Suite.t) :: [any]
-  def format(%Suite{scenarios: scenarios,
-                    configuration: %{formatter_options: %{console: config}}}) do
+  def format(%Suite{scenarios: scenarios, configuration: config}) do
+    config = console_configuration(config)
     scenarios
     |> Enum.group_by(fn(scenario) -> scenario.input_name end)
     |> Enum.map(fn({input, scenarios}) ->
@@ -88,6 +89,17 @@ defmodule Benchee.Formatters.Console do
     _ -> {:error, "Unknown Error"}
   end
 
+  defp console_configuration(%Configuration{
+                               formatter_options: %{console: config},
+                               unit_scaling: scaling_strategy}) do
+    if Map.has_key?(config, :unit_scaling), do: warn_unit_scaling()
+    Map.put config, :unit_scaling, scaling_strategy
+  end
+
+  defp warn_unit_scaling do
+    IO.puts "unit_scaling is now a top level configuration option, avoid passing it as a formatter option."
+  end
+
   @no_input_marker Benchee.Benchmark.no_input()
   defp input_header(input) do
     case input do

diff --git a/test/benchee/configuration_test.exs b/test/benchee/configuration_test.exs
@@ -45,10 +45,7 @@ defmodule Benchee.ConfigurationTest do
         time: 10,
         formatter_options: %{
           custom: %{option: true},
-          console: %{
-            comparison:    true,
-            unit_scaling:  :best
-          }
+          console: %{comparison: true}
         }
       }
 

diff --git a/test/benchee/formatters/console_test.exs b/test/benchee/formatters/console_test.exs
@@ -8,7 +8,9 @@ defmodule Benchee.Formatters.ConsoleTest do
   alias Benchee.{Suite, Statistics, Benchmark.Scenario}
 
   @console_config %{comparison: true, unit_scaling: :best}
-  @config %Benchee.Configuration{formatter_options: %{console: @console_config}}
+  @config %Benchee.Configuration{
+    formatter_options: %{console: %{comparison: true}}
+  }
   describe ".output" do
     test "formats and prints the results right to the console" do
       scenarios = [