update example to use best practices for parameter caching (#42)

* update docs to use BenchmarkTools serialization wrapper

* update example to use best practices for parameter caching

Author: jrevels

.gitignore

@@ -1,3 +1,4 @@
 *.jl.cov
 *.jl.*.cov
 *.jl.mem
+benchmark/params.jld

benchmark/benchmarks.jl

@@ -1,5 +1,4 @@
 using BenchmarkTools
-using JLD
 
 # Define a parent BenchmarkGroup to contain our suite
 const suite = BenchmarkGroup()
@@ -22,8 +21,14 @@ for f in (sin, cos, tan)
     end
 end
 
-# Load the suite's cached parameters as part of including the file. This is much
-# faster and more reliable than re-tuning `suite` every time the file is included
-paramspath = joinpath(Pkg.dir("BenchmarkTools"), "benchmark", "params.jld")
-# tune!(suite); JLD.save(paramspath, "suite", params(suite));
-loadparams!(suite, JLD.load(paramspath, "suite"), :evals, :samples);
+# If a cache of tuned parameters already exists, use it, otherwise, tune and cache
+# the benchmark parameters. Reusing cached parameters is faster and more reliable
+# than re-tuning `suite` every time the file is included.
+paramspath = joinpath(dirname(@__FILE__), "params.jld")
+
+if isfile(paramspath)
+    loadparams!(suite, BenchmarkTools.load(paramspath, "suite"), :evals, :samples);
+else
+    tune!(suite)
+    BenchmarkTools.save(paramspath, "suite", params(suite));
+end

benchmark/params.jld

@@ -918,17 +918,17 @@ BenchmarkTools.BenchmarkGroup:
 # tune the suite to configure benchmark parameters
 julia> tune!(suite);
 
-julia> using JLD
-
-# save the suite's parameters using JLD
-julia> JLD.save("params.jld", "suite", params(suite));
+# save the suite's parameters using a thin wrapper
+# over JLD (this wrapper maintains compatibility
+# across BenchmarkTools versions)
+julia> BenchmarkTools.save("params.jld", "suite", params(suite));
 ```
 
 Now, instead of tuning `suite` every time we load the benchmarks in a new Julia session, we can simply load the parameters in the JLD file using the `loadparams!` function:
 
 ```julia
 # syntax is loadparams!(group, paramsgroup, fields...)
-julia> loadparams!(suite, JLD.load("params.jld", "suite"), :evals, :samples);
+julia> loadparams!(suite, BenchmarkTools.load("params.jld", "suite"), :evals, :samples);
 ```
 
 Caching parameters in this manner leads to a far shorter turnaround time, and more importantly, much more consistent results.

doc/manual.md

@@ -183,6 +183,14 @@ end
 
 Return an iterator over `x`'s leaf index/value pairs. Relevant manual documentation can be found [here](manual.md#indexing-into-a-benchmarkgroup-using-a-vector).
 
+##### `save(filename, args...)`
+
+Not exported. This function is a thin wrapper around a call to `JLD.save(filename, args...)` that maintains compatibility between BenchmarkTools versions.
+
+##### `load(filename, args...)`
+
+Not exported. This function is a thin wrapper around a call to `JLD.load(filename, args...)` that maintains compatibility between BenchmarkTools versions.
+
 ##### `loadparams!(x::Parameters, y::Parameters, fields...)`
 ##### `loadparams!(x::Benchmark, y::Parameters, fields...)`
 ##### `loadparams!(x::BenchmarkGroup, y::BenchmarkGroup, fields...)`