Implements the concept of a measured function for benchmarking.
Criterium's metric collection works on a Measured instance. A Measured represents a benchmarkable unit of code, consisting of:
The Measured implements a timed, batch invocation interface that:
Warmup Customization: Functions may have different complexities based on their inputs. If warmup always uses the same arguments, JIT may over-specialize for those inputs. The warmup-args-fn field enables using varied inputs during warmup for more representative JIT optimization.
Priority rule for warmup arguments:
While Criterium automatically creates Measured instances for expressions, you can also construct custom ones for special measurement needs.
Implements the concept of a measured function for benchmarking. Criterium's metric collection works on a Measured instance. A Measured represents a benchmarkable unit of code, consisting of: - A function to execute and measure - An arguments generator to prevent constant folding - Optional symbolic representation for debugging - Optional warmup arguments generator for JIT optimization The Measured implements a timed, batch invocation interface that: - Supports multiple evaluations per timing sample for fast expressions - Guarantees zero garbage allocation during measurement - Prevents constant folding optimization of inputs Warmup Customization: Functions may have different complexities based on their inputs. If warmup always uses the same arguments, JIT may over-specialize for those inputs. The warmup-args-fn field enables using varied inputs during warmup for more representative JIT optimization. Priority rule for warmup arguments: 1. The bench macro's :warmup-args-fn option (baked into Measured at compile time) 2. Measured-level warmup-args-fn (from measured constructor or with-warmup-args-fn) 3. Fall back to regular args-fn While Criterium automatically creates Measured instances for expressions, you can also construct custom ones for special measurement needs.
(args measured)Generate the input state for a measured.
Returns a value suitable for passing to the measured's function. The returned value is created fresh each time to prevent constant folding optimizations.
Generate the input state for a measured. Returns a value suitable for passing to the measured's function. The returned value is created fresh each time to prevent constant folding optimizations.
(callable f)(callable sf f)(callable sf f warmup-args-fn)Return a Measured for a function.
With one argument, the function takes no arguments.
With two arguments, the first is a setup function that returns a sequence of arguments to pass to the function.
With three arguments, the third is a warmup-args-fn that returns arguments to use during warmup instead of the setup function.
Return a Measured for a function. With one argument, the function takes no arguments. With two arguments, the first is a setup function that returns a sequence of arguments to pass to the function. With three arguments, the third is a warmup-args-fn that returns arguments to use during warmup instead of the setup function.
(expr expr)(expr expr options)Return a Measured for the given expression.
The expression is wrapped in a function.
When the expression is a list form, it is treated as a function call. The function arguments are evaluated once by an arguments function, which returns a vector. That vector is passed to the function wrapper and destructured into the individual arguments.
Local bindings from the enclosing scope can be used as arguments in the expression.
The harness stops constant folding and dead-code elimination. Each
argument is stored once in an atomic cell before timing starts, the
cell is published once to the blackhole (so escape analysis can not
prove it thread-local), and the cell is read with getOpaque on every
loop iteration, so the JIT keeps the work in the loop. The loop result
goes to a blackhole. For very cheap expressions, the reported time
includes a small per-argument read cost (about 0.07 ns primitive,
0.2-0.35 ns reference) that is not subtracted. Every primitive argument,
including boolean, byte, short and char, reads through the opaque
barrier; only array-typed arguments use a plain binding.
Return a Measured for the given expression. The expression is wrapped in a function. When the expression is a list form, it is treated as a function call. The function arguments are evaluated once by an arguments function, which returns a vector. That vector is passed to the function wrapper and destructured into the individual arguments. Local bindings from the enclosing scope can be used as arguments in the expression. The harness stops constant folding and dead-code elimination. Each argument is stored once in an atomic cell before timing starts, the cell is published once to the blackhole (so escape analysis can not prove it thread-local), and the cell is read with `getOpaque` on every loop iteration, so the JIT keeps the work in the loop. The loop result goes to a blackhole. For very cheap expressions, the reported time includes a small per-argument read cost (about 0.07 ns primitive, 0.2-0.35 ns reference) that is not subtracted. Every primitive argument, including `boolean`, `byte`, `short` and `char`, reads through the opaque barrier; only array-typed arguments use a plain binding.
(invoke measured state eval-count)Invoke the given Measured.
Calls the Measured's function with the given state and eval-count.
The state can be created with args.
Returns a tuple of [elapsed-time expr-value] where:
Guarantees zero garbage allocation during measurement.
Invoke the given Measured. Calls the Measured's function with the given state and eval-count. The state can be created with `args`. Returns a tuple of [elapsed-time expr-value] where: - elapsed-time is a long representing the execution time in nanoseconds - expr-value is the result of evaluating the measured expression Guarantees zero garbage allocation during measurement.
(measured args-fn f)(measured args-fn f expr-fn)(measured args-fn f expr-fn warmup-args-fn)Return a Measured for a function that can be benchmarked.
The Measured is the basic unit of measurement. A Measured consists of
an arguments generation funtion and a function to be measured. The
function to be measured takes the result of calling the arrguments
function and an eval-count as arguments, ie. (f (args-fn) eval-count), and returns an [elapsed-time expr-value] tuple.
The arguments function is used to prevent constant folding for
constant inputs. A Measured built by expr also reads each argument
with an opaque read on every iteration, so the JIT can not hoist the
expression out of the loop; see expr for the cost of this.
The eval-count allows the function to time multiple evaluations of the subject expression, so that we can measure expressions that are faster than the timer granularity.
expr-fn, if specified, returns a symbolic representation of the measured, for inspection purposes (unused internally).
warmup-args-fn, if specified, provides arguments for warmup phase instead of args-fn. This allows warmup with more varied inputs to get more representative JIT optimization.
Return a Measured for a function that can be benchmarked. The Measured is the basic unit of measurement. A Measured consists of an arguments generation funtion and a function to be measured. The function to be measured takes the result of calling the arrguments function and an eval-count as arguments, ie. `(f (args-fn) eval-count)`, and returns an `[elapsed-time expr-value]` tuple. The arguments function is used to prevent constant folding for constant inputs. A Measured built by `expr` also reads each argument with an opaque read on every iteration, so the JIT can not hoist the expression out of the loop; see `expr` for the cost of this. The eval-count allows the function to time multiple evaluations of the subject expression, so that we can measure expressions that are faster than the timer granularity. expr-fn, if specified, returns a symbolic representation of the measured, for inspection purposes (unused internally). warmup-args-fn, if specified, provides arguments for warmup phase instead of args-fn. This allows warmup with more varied inputs to get more representative JIT optimization.
(measured? x)Predicate for x being a Measured.
Predicate for x being a Measured.
(warmup-args measured)Generate warmup input state for a measured.
Returns warmup-args-fn result if present, otherwise falls back to args-fn. This allows warmup to use more varied inputs for better JIT optimization while measurement uses the actual benchmark inputs.
Generate warmup input state for a measured. Returns warmup-args-fn result if present, otherwise falls back to args-fn. This allows warmup to use more varied inputs for better JIT optimization while measurement uses the actual benchmark inputs.
(with-args-fn measured new-args-fn)Return a new Measured with the args-fn replaced. Preserves the measurement function, symbolic representation, and warmup-args-fn.
This is useful for running the same measured expression with different input generators, e.g., when benchmarking across a parameter space.
Return a new Measured with the args-fn replaced. Preserves the measurement function, symbolic representation, and warmup-args-fn. This is useful for running the same measured expression with different input generators, e.g., when benchmarking across a parameter space.
(with-warmup-args-fn measured new-warmup-args-fn)Return a new Measured with the warmup-args-fn set or replaced. Preserves the measurement function, args-fn, and symbolic representation.
This is useful for adding varied warmup inputs to an existing Measured, for example when running domain analysis where all implementations should share the same warmup strategy.
Return a new Measured with the warmup-args-fn set or replaced. Preserves the measurement function, args-fn, and symbolic representation. This is useful for adding varied warmup inputs to an existing Measured, for example when running domain analysis where all implementations should share the same warmup strategy.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |