jmh.core
Clojure benchmarking with JMH.
profilers
(profilers)
Return a set of profiler maps. If :supported, the profiler :name is
available for use with `run`.
register-profiler-alias!
(register-profiler-alias! k x)
Accepts a key `k` and a value `x` suitable for the `run` :profilers
option. Registers the given profiler value under the alias k. This
name may subsequently be used in place of x. Returns nil.
run
(run env)
(run env opts)
Run the :benchmarks given in env. Returns the benchmark results as a
sequence of maps. Options include:
:compile-path directory which to write .class files to. Must be on
the classpath. The default is to use *compile-path*
and should not generally need to be changed if using
a tool such as Leiningen or similar.
:externs advanced option. See below.
:fail-on-error halt execution on any benchmark exception. Defaults
to true. Note that if this is false, benchmarks that
fail will be missing from the returned sequence.
:ignore-lock do not fail if the jmh lock file cannot be obtained.
:instrument debugging switch. If true, capture call information
for each state and benchmark fn during the run. Note
that this option disables jmh forking. The data is
provided as :jmh/log metadata on the returned seq.
:iterations map. If key :gc is true, a garbage collection is
forced between each iteration. If key :synchronize
is false, worker threads don't wait until each is
ready to run an iteration before proceeding.
:params map. Parameters to add or override from env.
Parameters for externs (see below) are provided via
a special :jmh/externs key which gives a nested map.
:profilers seq. Profilers to enable while benchmarking. See
`profilers`. External profilers may be specified by
giving the class as package-prefixed symbol, Class
object, or tuple of [class initialization-string].
:progress callback fn that will receive periodic progress
events. Overridden by :status.
:select keyword or seq of selector keywords for filtering
benchmarks to run.
:status by default, jmh output is suppressed. If true,
display the log output while running. If a string,
write it to the given file. Overrides :progress.
:type keyword or keyword seq. Aliases for common option
sets. For example, :quick. Option groups described
in env are automatically merged for convenience. See
the `jmh.option` namespace for more.
:verbose if true or :extra, generate additional :status
output during the run. If :silent or false, don't
collect any. Provide :normal for the default.
:warmups map. The :mode key is one of :indi, :bulk, or
:bulk-indi. See the jmh WarmupMode javadoc for more.
The :select key may also be given to run additional
benchmark fns only during warmup.
:warnings if false, do not check for JVM configuration issues.
Along with the above, benchmark options can be specified as well to
add to or override those given in the env.
Additional advanced options are described below.
External benchmark classes may be run along side Clojure ones. The
:externs key gives a sequence of class names to process. Each item may
be a class name, or a map, the latter gives a :class name along with
an optional :select method regex and a boolean :warmup flag. Note that
the :select pattern is anchored to the beginning of the method name.
For example, to match methods ending with 'foo' use #".*foo$".
run-expr
macro
(run-expr expr)
(run-expr expr opts)
Benchmark an expression. Equivalent to: (run-fn (fn [] expr) opts).
run-fn
(run-fn f)
(run-fn f opts)
Benchmark a thunk (a fn of zero arguments). See `run` for details on
the available options. Returns a single result map.
Note that benchmarking this way precludes forking.