Module Unmark

module Unmark: sig .. end

Painless micro-benchmarks.

Theory of operation is TODO.

Examples at the end.

359b80f — homepage

type 'a fmt = Stdlib.Format.formatter -> 'a -> unit

Creating benchmarks

Benchmark construction is sufficient for most uses of the library. For a simple way to run the benchmarks, see Unmark_cli.

type bench

A labelled tree of code.

Leaves contain annotated functions. Inner nodes are purely organisational.

module Attr: sig .. end

Benchmark metadata.

val bench : ?attr:Attr.t -> string -> (unit -> 'a) -> bench

bench ?attr name f is a named benchmark measuring f.

attr are optional attributes. Attributes serve to attach user-defined metadata to the benchmark.

Note. Occurrences of '/' in name are removed in an unspecified way.

val group : string -> bench list -> bench

group name benchmarks is a named group of benchmarks.

Root nodes of benchmarks are renamed to avoid name clashes.

name behaves like above.

val group_f : init:(unit -> 'a) ->
       fini:('a -> unit) -> string -> ('a -> bench list) -> bench

group_f ~init ~fini name f is a group of benchmarks that depend on a temporarily acquired resource.

This is group name (f (init ())), except init and f are only invoked if the group is visited (e.g. to run the benchmarks), and fini is called on the result of init after the visit.

Apart from acquiring and releasing external resources, init/fini -- or simply constructing stuff in the body of f -- can be used to avoid expensive setup computations if the group is going to be skipped.

Detailed interface

The rest of the API is of interest for changing what is being measured, creating alternative benchmark runners, directly inspecting benchmarks, or analysing the results.

val log : Logs.src

Log source for this module.

module Measurement: sig .. end

Low-level measurement machinery.

module Benchmarks: sig .. end

Running and elimination of whole benchmarks suites.

module Estimate: sig .. end

Deepest numerology.

Examples

A single benchmark measuring f: unit -> t for some t:

let bm = bench "eff" f

A group of benchmarks:

let bm = group "things" [
  bench "this" f;
  bench "that" g;
]

Group nesting:

let bm = group "stuff" [
  group "more" [ bench "x" x ];
  group "less" [ bench "y" y ];
]

A group acquiring a resource:

let bm path = group_f "files" (fun fd ->
  [ bench "f1" (fun () -> f1 fd);
    bench "f2" (fun () -> f2 fd);
  ])
  ~init:Unix.(fun () -> openfile path [O_RDONLY] 0)
  ~fini:Unix.close

Using a group to delay construction of data:

let bm = group_f "big data" (fun () ->
  let really_big_value = ... in
  [ bench "f" (fun () -> f really_big_value) ]
  ) ~init:ignore ~fini:ignore

Independent variable.

Creates a group, containing 3 subgroups. Each subgroup instantiates f1 and f2 with a different argument. Leaf-level benchmarks are annotated with the argument, keyed by en.

let pp_int ppf = Format.fprintf ppf "%d"
let en = Attr.key pp_int ~name:"en"

let bm =
  let g n = group (Format.sprintf "size %d" n) [
    bench ~attr:(en n) "f1" (fun () -> f1 n);
    bench ~attr:(en n) "f2" (fun () -> f2 n);
  ] in
  group "effs" @@ List.map g [1; 10; 100]