1.2.1 Execution Stages

The execution flow of a test case is composed of three sequential stages:

1. Preparation Stage

   The Set Up stage receives the execution state object as a parameter and allocates the fixture for the test code and prepares the environment for its execution.

2. Test Stage
   • Automatic Test

     An automatic test receives the allocated fixture directly and does not have direct access to the execution state. It is invoked repeatedly by the framework and measures are sampled after certain amount of iterations.

   • Directed Test

     A directed test receives the framework execution state object (see State Reference) as its parameter, where the allocated fixture by the previous stage is stored. This is the concept used by Google Benchmark, where code must manually loop on the state.

3. Finalization Stage

   The Tear Down stage releases the resources allocated for the fixture and performs any other cleanup needed.

1.3.1 Predefined Meters

A meter is a device used to take measures (see Meter Reference for a detailed description.)

• None yet.

1.3.2 Predefined Clocks

The clock type controls the type of measurement performed by a chronometer or a timer. The library implements the following clock type definitions (see Time Reference) if they were available at build time:

• realtime:

  Wall clock time provided by the operating system. CLOCK_TAI is preferred when it is availableto CLOCK_REALTIME.

• monotonic:

  Non decreasing clock time, such as CLOCK_MONOTONIC.

• process:

  Process time, such as CLOCK_PROCESS_CPUTIME_ID.

• thread:

  Execution thread time.

1.3.3 Predefined Chronometers

A chronometer is a device used to measure time. It is an specialization of the micro_benchmark_meter type used to calculate the sample time and the total time (see Chronometer Reference for a detailed description.)

The following chronometers are implemented by the library:

• time_t (Always)

  Realtime chronometer based on the the C standard type time_t, retrieved from time function. It represents seconds, so its minimum resolution is one second.

• clock_t (Always)

  Process time chronometer based on the C standard type clock_t, retrieved from clock function. It overflows easily; this is not checked by the framework.

• gettimeofday (Optional)

  Realtime chronometer based on the function gettimeofday. Its values are represented by struct timeval.

• clock_gettime (Optional)

  Chronometer based on the function clock_gettime. Its minimum theoretical resolution is calculated based on the clock type selected (see Time Reference.) Its values are represented by struct timespec.

1.3.4 Predefined Timers

A timer is a device that is triggered after a predefined amount of time. They are used to calculate the sample time and the total time (see Timer Reference for a detailed description.)

The following timers are implemented by the library:

• chrono-adapter:

  Timer adapter from a provided chronometer (see Timer Provider Reference.)

• itimer:

  Timer based on the setitimer API. This timer only supports one timer per type.

• timer-t:

  Timer based on the timer_t API.

• timerfd:

  Timer based on the timerfd API, currently only supported on GNU systems based on Linux kernel.

1.4.1 Autoconf Macros

Common autoconf macros can be used to find the library, such as:

AC_SEARCH_LIBS([micro_benchmark_init], [mbenchmark], [...])

MicroBenchmark comes with some (experimental) macros too:

• Experimental: MICRO_BENCHMARK_CHECK_C

  Search MicroBenchmark library on some predefined routes and call AC_SUBST on the following variables:

  • MICRO_BENCHMARK_CPPFLAGS:

    Contains the compiler flags needed to find the headers of the local installation of MicroBenchmark.

  • MICRO_BENCHMARK_CFLAGS:

    Contains the compiler flags needed to compile and link a program with MicroBenchmark.

  • MICRO_BENCHMARK_LIBS:

    Contains the linker flags needed to link a program with MicroBenchmark.

  • MICRO_BENCHMARK_LTLIBS:

    Contains a reference to MicroBenchmark libtool file, when available.

• Experimental: MICRO_BENCHMARK_CHECK_CXX

  Search MicroBenchmark C++ library on some predefined routes and call AC_SUBST on the following variables:

  • MICRO_BENCHMARK_CPPFLAGS:

    Contains the compiler flags needed to find the headers of the local installation of MicroBenchmark.

  • MICRO_BENCHMARK_CXXFLAGS:

    Contains the compiler flags needed to compile and link a C++ program with MicroBenchmark.

  • MICRO_BENCHMARK_CXXLIBS:

    Contains the linker flags needed to link a program against MicroBenchmark C++ binding.

  • MICRO_BENCHMARK_CXXLTLIBS:

    Contains the reference to MicroBenchmark C++ libtool file, when available.

• Experimental: MICRO_BENCHMARK_CHECK_GUILE

  Check that the modules availability and the library version.

This could be a basic example of their usage:

configure.ac:
---

@dots{}
AS_IF([@dots{}],
 [dnl To substitute CFLAGS/LIBS/LTLIBS
  MICRO_BENCHMARK_CHECK_C
  @dots{}
  dnl To substitute CXXFLAGS/CXXLIBS/CXXLTLIBS
  MICRO_BENCHMARK_CHECK_CXX
  @dots{}
  dnl For Guile, only checks are performed
  MICRO_BENCHMARK_CHECK_GUILE
 ])
@dots{}

---

Makefile.am:
---

@dots{}
ctest_CFLAGS += $(MICRO_BENCHMARK_CFLAGS)
ctest_LIBS += $(MICRO_BENCHMARK_LIBS)
@dots{}
# For the C++ library
cpptest_CXXFLAGS += $(MICRO_BENCHMARK_CXXFLAGS)
cpptest_LIBS += $(MICRO_BENCHMARK_CXXLIBS)
@dots{}
# Or with libtool
ltctest_LDADD += $(MICRO_BENCHMARK_LTLIBS)
ltcxxlttest_LDADD += $(MICRO_BENCHMARK_CXXLTLIBS)
@dots{}

---

1.4.2 Other Build Systems

The following pkg-config modules are provided by MicroBenchmark.

• Experimental: mbenchmark.pc

  pkg-config [–cflags|–libs] mbenchmark

• Experimental: mbenchmark-c++.pc

  pkg-config [–cflags|–libs] mbenchmark-c++

For example, to compile a benchmark executable from a source file test.c (or test.cpp) using pkg-config, you could use the following command line:

$ gcc $(pkg-config --cflags --ldflags mbenchmark) -o test test.c
# Or for C++
$ g++ $(pkg-config --cflags --ldflags mbenchmark-c++) -o test-c++ test.cpp

1.4.3 Simple Tests

This section shows some basic code examples of MicroBenchmark usage.

This code generates a minimal (and not very useful) C benchmark:

#include <mbenchmark/all.h>
#include <unistd.h>

static void
test (void *unused)
{
  (void) unused;
  usleep (1000);
}

MICRO_BENCHMARK_REGISTER_SIMPLE_TEST (test);
MICRO_BENCHMARK_MAIN ();

This file can be found on the source code tree at doc/examples/basic.c. Lets go through its parts:

• The line #include <mbenchmark/all.h> includes all the needed files to use the library.
• The function void test (void *unused) is the code under test...
• ... which is registered by the macro MICRO_BENCHMARK_REGISTER_SIMPLE_TEST (test).
• To generate a main function, MICRO_BENCHMARK_MAIN() can be placed anywhere on the file scope.

This code could be compiled with a C++ compiler too. Nonetheless, C++14 or later code might use the features available through the C++ binding. This would be the equivalent example in C++:

(use-modules (mbenchmark))

(define (test . args)
  (usleep 1000))

(register-test! "test" #:test test)
(main (command-line))

This file can be found on the source code tree at doc/examples/basic.cxx. These are the main differences with the C interface:

• Instead of including #include <mbenchmark/all.h>, #include <mbenchmark/all.hpp> is included. These two files cannot be included together, as the macro names exported by them collide.
• The default test receives a reference to a std::vector<std::size_t> as its parameter, the one returned by sizes method on the state object (see C++ State Reference).
• The token returned by the register_test function (rtest) has to be declared at namespace level.

This would be its Guile equivalent:

(use-modules (mbenchmark))

(define (test . args)
  (usleep 1000))

(register-test! "test" #:test test)
(main (command-line))

This file can be found on the source code tree at doc/examples/basic.scm. Let’s see its parts:

• The module (mbenchmark) includes all the functionality needed.
• register-test! uses keywords for their arguments (see Guile Test Case Reference.)
• main could be provided with the -e main, but here it is explicit to allow its direct execution.

The execution of these examples would print something like this:

basic --brief --log-level=warn
⇒

Suite: basic (1 test execution)
====================================
Test Name | Iterations | It.Time (μ)
====================================
     test |       4026 |      1.22ms
====================================

1.4.4 Directed Test Cases

TODO

1.4.5 Test Constraints

The examples shown on the previous section use the library defaults, which could not be appropriate for your specific use case. MicroBenchmark includes several options to customize the environment where the test is executed (see Test Constraints Reference.)

The following examples show the basic constraint usage on the implemented languages:

#include <mbenchmark/all.h>
#include <unistd.h>

static void
limit_iterations (micro_benchmark_test_case test)
{
  micro_benchmark_test_case_limit_iterations (test, 300, 400);
  micro_benchmark_test_case_limit_samples (test, 2, 5);
}

static void
test_1 (void *ptr)
{
  (void) ptr;
  /* This test code will run for 300 to 400 iterations, taking
     measurements each 2 to 5 iterations. */
  usleep (10000);
}

MICRO_BENCHMARK_REGISTER_SIMPLE_TEST (test_1);
MICRO_BENCHMARK_CONSTRAINT_TEST ("test_1", limit_iterations);

static void
limit_time (micro_benchmark_test_case test)
{
  micro_benchmark_clock_time max = { 1, 0 };
  micro_benchmark_test_case_set_max_time (test, max);
}

static void
test_2 (void *ptr)
{
  (void) ptr;
  /* This test code will run for 1 second. */
  usleep (10000);
}

MICRO_BENCHMARK_REGISTER_SIMPLE_TEST (test_2);
MICRO_BENCHMARK_CONSTRAINT_TEST ("test_2", limit_time);

MICRO_BENCHMARK_MAIN ();

#include <mbenchmark/all.hpp>
#include <chrono>
#include <thread>

namespace
{
  using micro_benchmark::with_constraints;

  void
  test_1 (std::vector<std::size_t> const&)
  {
    std::this_thread::sleep_for (std::chrono::milliseconds(10));
  }

  void
  limit_iterations (micro_benchmark::test_case& test)
  {
    test.limit_iterations (300, 400);
    test.limit_samples (2, 5);
  }

  auto rt1 = micro_benchmark::register_test (with_constraints,
                                             "test_1", limit_iterations,
                                             test_1);
  void
  test_2 (std::vector<std::size_t> const&)
  {
    std::this_thread::sleep_for (std::chrono::milliseconds(10));
  }

  void
  limit_time (micro_benchmark::test_case& test)
  {
    test.max_time (std::chrono::seconds (1));
  }

  auto rt2 = micro_benchmark::register_test (with_constraints,
                                             "test_2", limit_time,
                                             test_2);
}

MICRO_BENCHMARK_MAIN ();

(define (test-1)
  (usleep 10000))

(register-test! "test-1" #:test test-1
                ;; This test will run for 300 to 400 iterations...
                #:min-iterations 300
                #:max-iterations 400
                ;; ... taking measurements each 2 to 5 iterations.
                #:min-sample-iterations 2
                #:max-sample-iterations 5)

(register-test! "test-2" #:test test-1
                ;; This test will run for 1 second.
                #:max-time 1)

(main (command-line))

Their output could look like this:

constraints --brief --log-level=warn
⇒

Suite: constraints (2 test executions)
====================================
Test Name | Iterations | It.Time (μ)
====================================
   test_1 |        400 |      10.3ms
   test_2 |         97 |      10.3ms
====================================

1.4.6 Test Dimensions

Usually, we want to provide different inputs to the test code in order to compare its behavior. To this end, MicroBenchmark allows to control the sizes provided to the test (see Test Constraints Reference), which can be used to produce tailored input.

The following examples show how to control the input of the test code:

#include <mbenchmark/all.h>
#include <unistd.h>

static void
one_dimension (micro_benchmark_test_case test)
{
  /* This test will have three dimensions, but four different values
     on them, so only one execution will be performed.  */
  const size_t sizes[] = { 1, 2, 3, 4 };
  const size_t ssizes = sizeof (sizes) / sizeof (*sizes);
  micro_benchmark_test_case_add_dimension (test, ssizes, sizes);
}

static size_t *
set_up_1d (micro_benchmark_test_state state)
{
  /* Prepare the data */
  static size_t s;
  s = micro_benchmark_state_get_size (state, 0) * 100000;
  return &s;
}

static void
test_1d (size_t *sz)
{
  /* test code */
  usleep (*sz);
}

MICRO_BENCHMARK_REGISTER_AUTO_TEST (set_up_1d, test_1d, 0);
MICRO_BENCHMARK_CONSTRAINT_TEST ("test_1d", one_dimension);

static void
three_dimensions (micro_benchmark_test_case test)
{
  /* This test will have three dimensions, but no variation on them,
     so only one execution will be performed.  */
  const size_t sizes[] = { 1, 2, 3 };
  micro_benchmark_test_case_add_dimension (test, 1, sizes + 0);
  micro_benchmark_test_case_add_dimension (test, 1, sizes + 1);
  micro_benchmark_test_case_add_dimension (test, 1, sizes + 2);
}

static size_t *
set_up_3d (micro_benchmark_test_state state)
{
  /* Prepare the data */
  static size_t s[3];
  s[0] = micro_benchmark_state_get_size (state, 0) * 10000;
  s[1] = micro_benchmark_state_get_size (state, 1) * 100000;
  s[2] = micro_benchmark_state_get_size (state, 2) * 1000000;
  return s;
}

static void
test_3d (size_t *sz)
{
  /* test code */
  usleep (sz[0] + sz[1] + sz[2]);
}

MICRO_BENCHMARK_REGISTER_AUTO_TEST (set_up_3d, test_3d, 0);
MICRO_BENCHMARK_CONSTRAINT_TEST ("test_3d", three_dimensions);

MICRO_BENCHMARK_MAIN ();

#include <mbenchmark/all.hpp>
#include <chrono>
#include <thread>

namespace
{
  using micro_benchmark::with_constraints;

  void
  one_dimension (micro_benchmark::test_case& test)
  {
    test.add_dimension ({ 1, 2, 3 });
  }

  void
  test_1d (std::vector<std::size_t> const& v)
  {
    std::this_thread::sleep_for (std::chrono::milliseconds (v[0] * 100));
  }

  auto t1d = micro_benchmark::register_test (with_constraints, "test1d",
                                             one_dimension, test_1d);

  void
  three_dimensions (micro_benchmark::test_case& test)
  {
    test.add_dimension ({ 1 });
    test.add_dimension ({ 10 });
    test.add_dimension ({ 100 });
  }

  void
  test_3d (std::vector<std::size_t> const& v)
  {
    std::this_thread::sleep_for (std::chrono::milliseconds (v[0] + v[1] + v[2]));
  }

  auto t3d = micro_benchmark::register_test (with_constraints, "test3d",
                                             three_dimensions, test_3d);

}

MICRO_BENCHMARK_MAIN ();

(define (test1d n)
  (usleep (* n 100000)))

(register-test! "test1d" #:test test1d
                #:dimensions '((1 2 3)))

(define (test3d x y z)
  (usleep (* 100000 (+ x y z))))

(register-test! "test3d" #:test test3d
                #:dimensions '((1) (2) (3)))

(main (command-line))

This could be their output:

dimensions --brief --log-level=warn
⇒

Suite: dimensions (5 test executions)
========================================
    Test Name | Iterations | It.Time (μ)
========================================
      test_1d |         -- |          --
    test_1d/1 |         50 |       100ms
    test_1d/2 |         25 |       200ms
    test_1d/3 |         17 |       300ms
    test_1d/4 |         13 |       400ms
----------------------------------------
test_3d/1/2/3 |          2 |       3.21s
========================================

2.1.1 Runtime Requirements

MicroBenchmark uses the following components at runtime:

• C library

  Several functions from the library are used at runtime. These include mathematical functions for the statistical calculations. Some configurations may use realtime facilities from the system.

• GNU libunistring

  Output facilities use GNU libunistring for strings manipulation.

• C++ Standard Library (Optional)

  The C++ binding may use templates such as std::basic_string and std::function as implementation details, even when the public interface does not depend on them.

• GNU Guile (Optional)

  Guile binding uses the modern foreign function interface, which was introduced with Guile 2.2.

2.1.2 Build Requirements

The generic build process from MicroBenchmark from a released source tarball have a reduced set of dependencies. These are the packages required:

• Bourne Shell and core utilities
• GNU sed or a compatible implementation
• GNU awk or a compatible implementation
• GNU grep or a compatible implementation
• GNU tar or a compatible implementation
• Make

  For the build recipes and test suite.

• C99 toolchain

  This release has passed all the tests with the following toolchains:

  • x86_64-linux-gnu
    • GNU GCC 4.9.4 - 12.3.0
    • LLVM/clang 6.0.1 - 15.0.7

      Tests run on GNU Guix: GNU Binutils 2.38 and GNU libc 2.35.

• C++ toolchain (Optional)

  This release has passed all the tests with the following toolchains:

  • x86_64-linux-gnu
    • GNU G++ 5.5.0 - 12.3.0
    • LLVM/clang++ 6.0.1 - 15.0.7

      Tests run on GNU Guix: GNU Binutils 2.38 and GNU libc 2.35.

• GNU Guile (Optional)

  This release has passed all the tests with the following toolchain and GNU Guile combinations:

  • x86_64-linux-gnu
    • Guile 2.2.7 (GNU GCC 4.9.4 - 12.3.0; LLVM/clang 6.0.1 - 15.0.7)
    • Guile 3.0.9 (GNU GCC 4.9.4 - 12.3.0; LLVM/clang 6.0.1 - 15.0.7)

      Tests run on GNU Guix: GNU Binutils 2.38 and GNU libc 2.35.

• GNU gettext (Optional)

  MicroBenchmark uses GNU gettext (see GNU gettext) for its localization (see Configuration.)

• GNU Gcov (Optional)

  The coverage report generation (see Configuration) uses gcov (see gcov in GNU Gcov) or a compatible interface².

• GNU Texinfo (Optional)

  Info files can be found on the distributed tarballs, but the generation of the manual pages on html format requires a functional GNU Texinfo installation (see GNU Texinfo manual).

• TeX Distribution (Optional)

  The manual pages can be generated on dvi and pdf formats, which need a functional TeX distribution.

These are common package names for these dependencies:

• gcc
• libunistring-dev, libunistring-devel
• make
• gettext (Optional)
• g++ or gcc-c++ (Optional)
• texinfo (Optional)
• texlive (Optional)
• guile-3.0-dev, guile30-devel
• guile-2.2-dev, guile22-devel

2.1.3 Build From VCS Requirements

Some of the optional dependencies might be mandatory to build the software from VCS:

• GNU texinfo is not an optional requirement, as info files are generated from the sources.
• A TeX distribution is required for the make target distcheck.

There are some additional dependencies to build the MicroBenchmark from the git repository, in addition to git itself. The following software to compile MicroBenchmark after modifying its sources:

• GNU wget (Optional)

  The external dependencies build-aux/gitlog-to-changelog and build-aux/test-driver.scm will be downloaded automatically when they aren’t found on the source directory. You can avoid this placing them manually on the source tree.

• GNU Autotools

  MicroBenchmark uses GNU Autoconf (see GNU Autoconf) for the generation of configure. GNU Automake (see GNU Automake) is used for the generation of Makefile.in. GNU libtool (see GNU libtool) is needed for the library generation scripts. GNU autopoint (see autopoint in GNU autopoint) is needed for the internationalization support.

• GNU Autoconf Archive

  configure.ac uses the macro AX_CXX_COMPILE_STDCXX (see ax_cxx_compile_stdcxxx in GNU Autoconf Archive.)

• GNU indent (Optional)

  The target make indent-code and the script build-aux/indent.sh use GNU indent (see GNU indent) to format C source code.

These are common names for the packages providing these dependencies:

• git
• wget
• autoconf
• autoconf-archive
• automake
• autopoint
• libtool
• indent

3.2.1 Console Output

NOTE: This format is under development and may change..

The usual output looks like this:

Suite: console (1 test execution)
=========================================================
     Test Name | Iterations | It.Time (μ/σ)  | Total Time
=========================================================
     Self-Test |         -- |             -- |         --
         empty |      65536 |  22.7ns/2.89ns |    0.3484s
       barrier |      65536 |  23.1ns/2.19ns |    0.3508s
    read+write |      65536 |  29.6ns/1.13ns |    0.3521s
      addition |      65536 |  32.7ns/1.71ns |    0.3529s
multiplication |      65536 |  34.8ns/1.16ns |    0.3513s
         empty |      65536 |  23.6ns/2.88ns |    0.3536s
---------------------------------------------------------
          test |       3994 | 1.25ms/0.074ms |    5.0912s
=========================================================

And here are all the possible values:

Suite: console (1 test execution)
======================================================================================================================================================
     Test Name | Total It. | Iterations | It.Time (μ/σ²/σ)        | Total S. | Samples | S.Time (μ/σ²/σ)       | S.Iter. (μ/σ²/σ) | Total Time | Sizes
======================================================================================================================================================
     Self-Test |        -- |         -- |                      -- |       -- |      -- |                    -- |               -- |         -- |    --
         empty |     65536 |      65536 |   21.1ns/8.06ns²/2.84ns |       58 |      58 |  24.1μs/189μs²/13.7μs |  1130/373162/611 |    0.3273s |   {0}
       barrier |     65536 |      65536 |   22.3ns/2.00ns²/1.41ns |       59 |      59 |  24.7μs/195μs²/14.0μs |  1111/393171/627 |    0.3430s |   {1}
    read+write |     65536 |      65536 |   29.3ns/8.21ns²/2.87ns |       60 |      60 |  31.6μs/334μs²/18.3μs |  1092/398707/631 |    0.3459s |   {2}
      addition |     65536 |      65536 |   32.2ns/6.57ns²/2.56ns |       60 |      60 |  34.9μs/398μs²/19.9μs |  1092/390244/625 |    0.3470s |   {3}
multiplication |     65536 |      65536 |   34.6ns/2.04ns²/1.43ns |       60 |      60 |  37.7μs/460μs²/21.4μs |  1092/383910/620 |    0.3485s |   {4}
         empty |     65536 |      65536 |   22.6ns/3.05ns²/1.75ns |       60 |      60 |  24.5μs/198μs²/14.1μs |  1092/386938/622 |    0.3484s |   {5}
------------------------------------------------------------------------------------------------------------------------------------------------------
          test |      3860 |       3860 | 1.29ms/0.002ms²/0.045ms |      311 |     311 | 16.0ms/78.1ms²/8.83ms |   12.4/47.5/6.89 |    5.0819s |     ∅
======================================================================================================================================================
------------------------------------------------------------------------------------------------------------------------------------------------------
------------------------------------------------------------------------------------------------------------------------------------------------------

3.2.2 Lisp Output

This format is compatible with Lisp’s read procedure, and can be used for further processing of the collected data.

NOTE: The format is under development and may change.

The usual output looks like this:

(suite (name "lisp")
  (test (name "Self-Test")
    (execution (number 0)
      (name "empty")
      (total-time 0.326749 "s")
      (iterations 65536)
      (iteration-time
        (mean 22.072614 "ns")
        (std-deviation 4.105545 "ns")))
    (execution (number 1)
      (name "barrier")
      (total-time 0.326562 "s")
      (iterations 65536)
      (iteration-time
        (mean 21.374931 "ns")
        (std-deviation 1.093298 "ns")))
    (execution (number 2)
      (name "read+write")
      (total-time 0.333746 "s")
      (iterations 65536)
      (iteration-time
        (mean 28.694221 "ns")
        (std-deviation 3.253493 "ns")))
    (execution (number 3)
      (name "addition")
      (total-time 0.345400 "s")
      (iterations 65536)
      (iteration-time
        (mean 38.210674 "ns")
        (std-deviation 25.125504 "ns")))
    (execution (number 4)
      (name "multiplication")
      (total-time 0.339907 "s")
      (iterations 65536)
      (iteration-time
        (mean 35.148271 "ns")
        (std-deviation 5.568858 "ns")))
    (execution (number 5)
      (name "empty")
      (total-time 0.332254 "s")
      (iterations 65536)
      (iteration-time
        (mean 21.904489 "ns")
        (std-deviation 1.905702 "ns")))
    (number-of-runs 6))
  (test (name "test")
    (execution (number 0)
      (name "test")
      (total-time 5.087626 "s")
      (iterations 3981)
      (iteration-time
        (mean 1.240041 "ms")
        (std-deviation 0.074364 "ms")))
    (number-of-runs 1))
  (number-of-tests 2))

And here are all the possible values:

(suite (name "lisp")
  (test (name "Self-Test")
    (execution (number 0)
      (name "empty")
      (dimensions (0))
      (total-time 0.314982 "s")
      (total-iterations 65536)
      (iterations 65536)
      (total-samples 57)
      (used-samples 57)
      (iteration-time
        (mean 20.941117 "ns")
        (std-deviation 5.240370 "ns")
        (variance 27.461475 "ns²"))
      (sample-time
        (mean 24.478947 "μs")
        (std-deviation 16.031848 "μs")
        (variance 257.020146 "μs²"))
      (sample-iterations
        (mean 1149.754386)
        (std-deviation 629.857787)
        (variance 396720.831454))
      (custom-meters (total 0)))
    (execution (number 1)
      (name "barrier")
      (dimensions (1))
      (total-time 0.323575 "s")
      (total-iterations 65536)
      (iterations 65536)
      (total-samples 57)
      (used-samples 57)
      (iteration-time
        (mean 21.163393 "ns")
        (std-deviation 0.844636 "ns")
        (variance 0.713410 "ns²"))
      (sample-time
        (mean 24.239070 "μs")
        (std-deviation 13.764559 "μs")
        (variance 189.463080 "μs²"))
      (sample-iterations
        (mean 1149.754386)
        (std-deviation 652.575592)
        (variance 425854.902882))
      (custom-meters (total 0)))
    (execution (number 2)
      (name "read+write")
      (dimensions (2))
      (total-time 0.322978 "s")
      (total-iterations 65536)
      (iterations 65536)
      (total-samples 57)
      (used-samples 57)
      (iteration-time
        (mean 27.766774 "ns")
        (std-deviation 2.136562 "ns")
        (variance 4.564897 "ns²"))
      (sample-time
        (mean 31.624877 "μs")
        (std-deviation 17.903620 "μs")
        (variance 320.539599 "μs²"))
      (sample-iterations
        (mean 1149.754386)
        (std-deviation 652.000419)
        (variance 425104.545739))
      (custom-meters (total 0)))
    (execution (number 3)
      (name "addition")
      (dimensions (3))
      (total-time 0.324984 "s")
      (total-iterations 65536)
      (iterations 65536)
      (total-samples 58)
      (used-samples 58)
      (iteration-time
        (mean 31.652676 "ns")
        (std-deviation 7.132115 "ns")
        (variance 50.867060 "ns²"))
      (sample-time
        (mean 37.170897 "μs")
        (std-deviation 27.209318 "μs")
        (variance 740.347009 "μs²"))
      (sample-iterations
        (mean 1129.931034)
        (std-deviation 656.896073)
        (variance 431512.451301))
      (custom-meters (total 0)))
    (execution (number 4)
      (name "multiplication")
      (dimensions (4))
      (total-time 0.323793 "s")
      (total-iterations 65536)
      (iterations 65536)
      (total-samples 57)
      (used-samples 57)
      (iteration-time
        (mean 32.703045 "ns")
        (std-deviation 0.937458 "ns")
        (variance 0.878827 "ns²"))
      (sample-time
        (mean 37.474596 "μs")
        (std-deviation 21.326054 "μs")
        (variance 454.800575 "μs²"))
      (sample-iterations
        (mean 1149.754386)
        (std-deviation 656.408880)
        (variance 430872.617168))
      (custom-meters (total 0)))
    (execution (number 5)
      (name "empty")
      (dimensions (5))
      (total-time 0.326234 "s")
      (total-iterations 65536)
      (iterations 65536)
      (total-samples 58)
      (used-samples 58)
      (iteration-time
        (mean 21.576884 "ns")
        (std-deviation 2.229484 "ns")
        (variance 4.970598 "ns²"))
      (sample-time
        (mean 24.337345 "μs")
        (std-deviation 14.608577 "μs")
        (variance 213.410528 "μs²"))
      (sample-iterations
        (mean 1129.931034)
        (std-deviation 660.495265)
        (variance 436253.995160))
      (custom-meters (total 0)))
    (number-of-runs 6))
  (test (name "test")
    (execution (number 0)
      (name "test")
      (total-time 5.082051 "s")
      (total-iterations 3938)
      (iterations 3938)
      (total-samples 311)
      (used-samples 311)
      (iteration-time
        (mean 1.265120 "ms")
        (std-deviation 0.067238 "ms")
        (variance 0.004521 "ms²"))
      (sample-time
        (mean 15.978674 "ms")
        (std-deviation 8.834413 "ms")
        (variance 78.046855 "ms²"))
      (sample-iterations
        (mean 12.662379)
        (std-deviation 7.027033)
        (variance 49.379193))
      (custom-meters (total 0)))
    (number-of-runs 1))
  (number-of-tests 2))

3.2.3 Text Output

This format is compatible with GNU recutils (see GNU recutils), and can be used for further processing of the collected data.

NOTE: The format is under development and may change.

The usual output looks like this:

# Suite Name: recutils
# Number of tests: 2

Suite: recutils
Test: Self-Test
Test-Case: empty
Total-Time: 0.330962 seconds
Iterations: 65536
Iteration-Time: 21.889642 ns
Iteration-Time-Dev: 3.465406 ns


Suite: recutils
Test: Self-Test
Test-Case: barrier
Total-Time: 0.336391 seconds
Iterations: 65536
Iteration-Time: 22.075144 ns
Iteration-Time-Dev: 1.480519 ns


Suite: recutils
Test: Self-Test
Test-Case: read+write
Total-Time: 0.338262 seconds
Iterations: 65536
Iteration-Time: 28.806907 ns
Iteration-Time-Dev: 1.788922 ns


Suite: recutils
Test: Self-Test
Test-Case: addition
Total-Time: 0.335605 seconds
Iterations: 65536
Iteration-Time: 31.240347 ns
Iteration-Time-Dev: 1.614777 ns


Suite: recutils
Test: Self-Test
Test-Case: multiplication
Total-Time: 0.336565 seconds
Iterations: 65536
Iteration-Time: 33.552166 ns
Iteration-Time-Dev: 0.872344 ns


Suite: recutils
Test: Self-Test
Test-Case: empty
Total-Time: 0.336429 seconds
Iterations: 65536
Iteration-Time: 22.165482 ns
Iteration-Time-Dev: 1.831835 ns


Suite: recutils
Test: test
Test-Case: test
Total-Time: 5.087685 seconds
Iterations: 4019
Iteration-Time: 1.244888 ms
Iteration-Time-Dev: 0.070221 ms

And here are all the possible values:

# Suite Name: recutils
# Number of tests: 2

Suite: recutils
Test: Self-Test
Test-Case: empty
Test-Dimensions: (0)
Total-Time: 0.313433 seconds
Total-Iterations: 65536
Total-Samples: 57
Iterations: 65536
Samples: 57
Iteration-Time: 21.266609 ns
Iteration-Time-Dev: 3.854903 ns
Iteration-Time-Var: 14.860275 ns²
Sample-Time: 24.024211 μs
Sample-Time-Dev: 14.308473 μs
Sample-Time-Var: 204.732392 μs²
Iterations-Sample: 1149.754386 iterations
Iterations-Sample-Dev: 658.869331 iterations
Iterations-Sample-Var: 434108.795739 iterations


Suite: recutils
Test: Self-Test
Test-Case: barrier
Test-Dimensions: (1)
Total-Time: 0.324264 seconds
Total-Iterations: 65536
Total-Samples: 57
Iterations: 65536
Samples: 57
Iteration-Time: 22.271273 ns
Iteration-Time-Dev: 1.055291 ns
Iteration-Time-Var: 1.113640 ns²
Sample-Time: 25.427140 μs
Sample-Time-Dev: 14.430901 μs
Sample-Time-Var: 208.250895 μs²
Iterations-Sample: 1149.754386 iterations
Iterations-Sample-Dev: 653.540940 iterations
Iterations-Sample-Var: 427115.760025 iterations


Suite: recutils
Test: Self-Test
Test-Case: read+write
Test-Dimensions: (2)
Total-Time: 0.324357 seconds
Total-Iterations: 65536
Total-Samples: 57
Iterations: 65536
Samples: 57
Iteration-Time: 29.853592 ns
Iteration-Time-Dev: 0.998944 ns
Iteration-Time-Var: 0.997890 ns²
Sample-Time: 34.188228 μs
Sample-Time-Dev: 19.447461 μs
Sample-Time-Var: 378.203752 μs²
Iterations-Sample: 1149.754386 iterations
Iterations-Sample-Dev: 655.631110 iterations
Iterations-Sample-Var: 429852.152882 iterations


Suite: recutils
Test: Self-Test
Test-Case: addition
Test-Dimensions: (3)
Total-Time: 0.327395 seconds
Total-Iterations: 65536
Total-Samples: 58
Iterations: 65536
Samples: 58
Iteration-Time: 32.130466 ns
Iteration-Time-Dev: 1.723760 ns
Iteration-Time-Var: 2.971349 ns²
Sample-Time: 36.404397 μs
Sample-Time-Dev: 21.188594 μs
Sample-Time-Var: 448.956513 μs²
Iterations-Sample: 1129.931034 iterations
Iterations-Sample-Dev: 638.763055 iterations
Iterations-Sample-Var: 408018.240774 iterations


Suite: recutils
Test: Self-Test
Test-Case: multiplication
Test-Dimensions: (4)
Total-Time: 0.326852 seconds
Total-Iterations: 65536
Total-Samples: 58
Iterations: 65536
Samples: 58
Iteration-Time: 35.174917 ns
Iteration-Time-Dev: 1.703684 ns
Iteration-Time-Var: 2.902540 ns²
Sample-Time: 39.356707 μs
Sample-Time-Dev: 22.986242 μs
Sample-Time-Var: 528.367301 μs²
Iterations-Sample: 1129.931034 iterations
Iterations-Sample-Dev: 664.098383 iterations
Iterations-Sample-Var: 441026.661827 iterations


Suite: recutils
Test: Self-Test
Test-Case: empty
Test-Dimensions: (5)
Total-Time: 0.328522 seconds
Total-Iterations: 65536
Total-Samples: 58
Iterations: 65536
Samples: 58
Iteration-Time: 22.131524 ns
Iteration-Time-Dev: 0.876206 ns
Iteration-Time-Var: 0.767737 ns²
Sample-Time: 24.892259 μs
Sample-Time-Dev: 14.260445 μs
Sample-Time-Var: 203.360286 μs²
Iterations-Sample: 1129.931034 iterations
Iterations-Sample-Dev: 649.394100 iterations
Iterations-Sample-Var: 421712.696915 iterations


Suite: recutils
Test: test
Test-Case: test
Test-Dimensions: ()
Total-Time: 5.089305 seconds
Total-Iterations: 3935
Total-Samples: 311
Iterations: 3935
Samples: 311
Iteration-Time: 1.269683 ms
Iteration-Time-Dev: 0.063774 ms
Iteration-Time-Var: 0.004067 ms²
Sample-Time: 15.970704 ms
Sample-Time-Dev: 8.820956 ms
Sample-Time-Var: 77.809264 ms²
Iterations-Sample: 12.652733 iterations
Iterations-Sample-Dev: 7.028627 iterations
Iterations-Sample-Var: 49.401597 iterations

4.2.1 Test Definition Reference

C Function Type: micro_benchmark_set_up_fun ¶

Its prototype is void *(*) (micro_benchmark_test_state).

C Function Type: micro_benchmark_tear_down_fun ¶

Its prototype is void (*) (micro_benchmark_test_state, void *).

C Function Type: micro_benchmark_auto_test_fun ¶

Its prototype is void (*) (void *).

C Function Type: micro_benchmark_test_fun ¶

Its prototype is void (*) (micro_benchmark_test_state).

C Data Type: micro_benchmark_test_definition { bool is_auto, micro_benchmark_set_up_fun set_up, micro_benchmark_tear_down_fun tear_down, micro_benchmark_auto_test_fun auto_test, micro_benchmark_test_fun test } ¶

Definition of a test case.

C Data Type: micro_benchmark_test_case_definition ¶

Opaque type of a registered test case.

C Test Function: const char * micro_benchmark_test_case_get_name (micro_benchmark_test_case test) ¶

Preconditions

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.

Effects:

1. None.

Postconditions:

1. The returned value is not NULL.
2. The returned value is the name used to register the test case.

C Test Function: micro_benchmark_test micro_benchmark_test_case_get_definition (micro_benchmark_test_case test) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.

Effects:

1. None.

Postconditions:

1. The returned value is not NULL.
2. The micro_benchmark_test_definition pointed by the returned value contains the same values as the one the provided to micro_benchmark_suite_register_test or MICRO_BENCHMARK_REGISTER_ macro family.

C Test Function: void micro_benchmark_test_case_set_enabled (micro_benchmark_test_case test, bool enabled) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.

Effects:

1. Any previous value provided to this function stops taking effect.
2. Activate the execution of test if enabled is true.
3. Deactivate the execution of test otherwise.

Postconditions:

1. The test will run if enabled is true.

C Test Function: void micro_benchmark_test_case_is_enabled (micro_benchmark_test_case test) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.

Effects:

1. Check the status of the test.

Postconditions:

1. If micro_benchmark_test_case_set_enabled was called with test as its parameter, the returned value is the value provided as its parameter.

C Test Function: void micro_benchmark_test_case_set_data (micro_benchmark_test_case test, void *data, void (*cleanup) (void *)) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.
3. cleanup points to a valid function for this signature.

Effects:

1. data is stored on the test case.
2. cleanup is stored on the test case.

Postconditions:

1. cleanup will be called with data as its parameter at the end of test lifetime.

C Test Function: void * micro_benchmark_test_case_get_data (micro_benchmark_test_case test) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.
3. cleanup points to a valid function for this signature.

Effects:

1. None.

Postconditions:

1. The returned value is the object pointer provided to micro_benchmark_test_case_set_data or NULL if micro_benchmark_test_case_set_data has not been called.

4.2.2 Test Constraints Reference

This subsection contains the different static constraints that can be applied to a test case.

The following functions modify the constraints applied to the test case execution:

C Test Function: void micro_benchmark_test_case_add_dimension (micro_benchmark_test_case test, size_t num_sizes, const size_t *sizes) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.
3. sizes points to a valid object or an array of them.
4. num_sizes is greater than 0.
5. num_sizes less or equal to the number of elements pointed by sizes.

Effects:

1. The test will be executed as many times as needed to explore all the possible combinations of the values pointed by sizes and all the previously stored combinations.

Postconditions:

1. test contains a disjoint copy of the values pointed by sizes.

C Test Function: size_t micro_benchmark_test_case_dimensions (micro_benchmark_test_case test) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test, micro_benchmark_suite_get_test and the associated micro_benchmark_suite is still valid.
   • test has been received as a parameter on a constraint definition and the scope of the function call is still active.

Effects:

1. The test will be executed as many times as needed to explore all the possible combinations of the values pointed by sizes and all the previously stored combinations.

Postconditions:

1. The returned value is the number of dimensions provided to test

C Test Function: void micro_benchmark_test_case_get_dimension (micro_benchmark_test_case test, size_t dimension, size_t *n_sizes, const size_t **sizes) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.
3. dimension is less than the value returned by micro_benchmark_test_case_dimensions.
4. n_sizes points to a valid object.
5. sizes points to a valid object.

Effects:

1. Write on the object pointed by n_sizes.
2. Write on the object pointed by sizes.

Postconditions:

1. The object pointed by sizes point to a valid array.
2. The object pointed by n_sizes contains the size of the array pointed by *sizes.

C Test Function: void micro_benchmark_test_case_skip_iterations (micro_benchmark_test_case test, size_t number) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.

Effects:

1. test is modified.

Postconditions:

1. test execution will perform number iterations before start taking performance measurements.

C Test Function: size_t micro_benchmark_test_case_iterations_to_skip (micro_benchmark_test_case test) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.

Effects:

1. None.

Postconditions:

1. The returned value is the number of iterations that test will performed before start taking performance measurements of its execution.
2. If micro_benchmark_test_case_skip_iterations has been called with test as its parameter, the returned value is the one provided to micro_benchmark_test_case_skip_iterations.

The following functions control the number of iterations performed by the code under test.

C Test Function: void micro_benchmark_test_case_limit_iterations (micro_benchmark_test_case test, size_t min_iterations, size_t max_iterations) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.
3. Either:
   • max_iterations is zero.
   • max_iterations is greater or equal than min_iterations.

Effects:

1. test is modified.

Postconditions:

1. The total number of iterations performed on each execution of test, without taking into account the iterations skipped, will be greater or equal than min_iterations.
2. If max_iterations is greater than 0, the total number of iterations performed on each execution of test, without taking into account the iterations skipped, will be less or equal than max_iterations.

C Test Function: size_t micro_benchmark_test_case_max_iterations (micro_benchmark_test_case test) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.

Effects:

1. None.

Postconditions:

1. The returned value is the maximum iterations performed on each execution of test, without taking into account the iterations skipped. A value of 0 means no limit on the number of iterations.
2. If micro_benchmark_test_case_limit_iterations was called and the parameter max_iterations was not zero, the returned value is the parameter provided to that call.

C Test Function: size_t micro_benchmark_test_case_min_iterations (micro_benchmark_test_case test) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.

Effects:

1. None.

Postconditions:

1. The returned value is the minimum iterations performed on each execution of test, without taking into account the iterations skipped.
2. If micro_benchmark_test_case_limit_iterations was called, the returned value is the value provided by the parameter min_iterations to that call.

The following functions limit of iterations performed on each measurement sample taken, or query these limits.

C Test Function: void micro_benchmark_test_case_limit_samples (micro_benchmark_test_case test, size_t min_iterations, size_t max_iterations) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.
3. Either:
   • max_iterations is zero.
   • max_iterations is greater or equal than min_iterations.

Effects:

1. test sample limits are modified, previous values provided to this functions stop taking effect.

Postconditions:

1. The total number of iterations performed on each measurement sample interval during the next execution of test will be greater or equal than min_iterations.
2. The total number of iterations performed on each measurement sample interval during the next execution of test will be less or equal than max_iterations, if max_iterations is a positive, non-zero value.

C Test Function: size_t micro_benchmark_test_case_min_sample_iterations (micro_benchmark_test_case test) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.

Effects:

1. None.

Postconditions:

1. The returned value is the minimum number of iterations performed on each measurement sample taken during test execution.
2. If micro_benchmark_test_case_limit_sample_iterations was called, the returned value is the value provided by the parameter min_iterations to that call.

C Test Function: size_t micro_benchmark_test_case_max_sample_iterations (micro_benchmark_test_case test) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.

Effects:

1. None.

Postconditions:

1. The returned value is the maximum number of iterations performed on each measurement sample taken during test execution.
2. If micro_benchmark_test_case_limit_sample_iterations was called, the returned value is the value provided by the parameter max_iterations to that call.

The following functions control the maximum time spent executing of test code.

C Test Function: void micro_benchmark_test_case_set_max_time (micro_benchmark_test_case test, micro_benchmark_clock_time deadline) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.

Effects:

1. test is modified.

Postconditions:

1. If deadline is non-zero, the test state will not request more iterations once the time spent on the test execution is greater or equal to the provided deadline and the minimum number of iterations has been reached.

C Test Function: micro_benchmark_clock_time micro_benchmark_test_case_get_max_time (micro_benchmark_test_case test) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.

Effects:

1. None.

Postconditions:

1. If micro_benchmark_test_case_set_max_time was called, the returned value is equivalent to the last value provided to that function.

C Test Function: void micro_benchmark_test_case_set_chrono (micro_benchmark_test_case test, micro_benchmark_clock_type type, micro_benchmark_chronometer_provider provider) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.
3. provider is not MICRO_BENCHMARK_CHRONO_PROVIDER_USER_PROVIDED.
4. provider is available for the system.
5. type is available for provider.

Effects:

1. test is modified.

Postconditions:

1. The clock represented by type/provider will be used to perform time measurements during test execution.

C Test Function: void micro_benchmark_test_case_set_custom_chrono (micro_benchmark_test_case test, micro_benchmark_clock_type type, micro_benchmark_meter meter) ¶

Preconditions:

1. Either:
   • test has been obtained through micro_benchmark_suite_register_test.
   • test has been obtained through micro_benchmark_suite_get_test.
   • test has been received as a parameter on a constraint definition and the scope of that function call is still active.
2. The suite associated to test is still valid.
3. meter is a chronometer.
4. meter implements type.

Effects:

1. A disjoint copy of the object pointed by meter is stored into test and initialized with type.

Postconditions:

1. An instance similar to meter will be used to perform time measurements during test execution.

C Test Function: void micro_benchmark_test_case_set_calculator (micro_benchmark_test_case test, micro_benchmark_custom_time_calculator calculator) ¶

Set custom statistical calculator for test.

C Data Type: micro_benchmark_custom_meter { micro_benchmark_meter meter, micro_benchmark_custom_sample_collector collector } ¶

Custom meter definition.

C Test Function: void micro_benchmark_test_case_add_meter (micro_benchmark_test_case test, micro_benchmark_custom_meter meter) ¶

Add custom meter to test. Data pointer provided by the user for test.

4.4.1 Suite Report Reference

C Data Type: micro_benchmark_report ¶

Opaque representation of the information collected by the suite execution.

The lifetime of these objects is bound to the suite that generated them. Calling micro_benchmark_suite_release ends the lifetime of all reports associated to that suite.

C Report Function: const char * micro_benchmark_report_get_name (micro_benchmark_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_suite_get_report.

Effects:

1. None.

Postconditions:

1. The value returned points to a valid, zero-ended array of characters.
2. The value returned is equivalent to the value provided to the call of micro_benchmark_suite_create that returned the suite associated to report.

C Report Function: size_t micro_benchmark_report_get_number_of_tests (micro_benchmark_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_suite_get_report.

Effects:

1. None.

Postconditions:

1. The returned value is the number of test cases executed by the suite associated to report.

C Report Function: micro_benchmark_test_report micro_benchmark_report_get_test_report (micro_benchmark_report report, size_t number) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_suite_get_report.
2. number is less than the value returned by micro_benchmark_report_get_number_of_tests (report).

Effects:

1. None.

Postconditions:

1. The returned value is a valid object.
2. The returned value contains the results of the test case number stored on report, counting from zero.

4.4.2 Test Report Reference

This section documents the reported data from a provided test case.

C Data Type: micro_benchmark_test_report ¶

Opaque representation of the information collected from a test case.

The lifetime of these objects is bound to the suite that generated them. Calling micro_benchmark_suite_release ends the lifetime of all reports associated to that suite.

C Report Function: const char * micro_benchmark_test_report_get_name (micro_benchmark_test_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_report_get_test_report.

Effects:

1. None.

Postconditions:

1. The value returned points to a valid, zero-ended array of characters.
2. The value returned is equivalent to the value provided at the micro_benchmark_suite_register_test call.

C Report Function: size_t micro_benchmark_test_report_get_num_executions (micro_benchmark_test_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_suite_get_report.

Effects:

1. None.

Postconditions:

1. The returned value is the number of executions performed of the test case associated to report.

C Report Function: micro_benchmark_exec_report micro_benchmark_test_report_get_exec_report (micro_benchmark_test_report report, size_t number) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_report_get_test_report.
2. number is less than the value returned by micro_benchmark_test_report_get_num_executions (report).

Effects:

1. None.

Postconditions:

1. The returned value is a valid object.
2. The returned value contains the results of the test execution number stored on report, counting from zero.

4.4.3 Test Execution Report

This section documents the reported data from an execution of a provided test.

C Data Type: micro_benchmark_exec_report ¶

Opaque representation of the information collected from a test case execution. Certain constraints, such as size dimensions, require several executions of the same test case.

The lifetime of these objects is bound to the suite that generated them. Calling micro_benchmark_suite_release ends the lifetime of all reports associated to that suite.

C Report Function: const char * micro_benchmark_exec_report_get_name (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned points to a valid, zero-ended array of characters, representing the name of this test execution.

C Report Function: void micro_benchmark_exec_report_get_sizes (micro_benchmark_exec_report report, const size_t **sizes, size_t *dimensions) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.
2. sizes must point to a valid object.
3. dimensions must point to a valid object.

Effects:

1. None.

Postconditions:

1. The object pointed by dimensions contains the size of the array pointed by sizes, or zero.
2. If dimensions is zero, the value of the object pointed by sizes is not changed. When dimensions is greater than zero, The object pointed by sizes points to an array of  objects whose values are equivalent to the ones provided for the test execution associated to report.

C Report Function: size_t micro_benchmark_exec_report_num_time_samples (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The number of time samples stored on report.

C Report Function: micro_benchmark_time_sample micro_benchmark_exec_report_get_time_sample (micro_benchmark_exec_report report, size_t n) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.
2. n is less than the value returned by micro_benchmark_exec_report_get_num_time_samples (report).

Effects:

1. None.

Postconditions:

1. The value returned is the the time sample n collected by the test case execution associated to report.

The following functions access to the aggregated statistical data of the test execution report.

C Report Function: size_t micro_benchmark_exec_report_get_iterations (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned is the number of sampled iterations by the test case execution associated to report.

C Report Function: size_t micro_benchmark_exec_report_total_iterations (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned is the total number of iterations performed by the test case execution associated to report.

C Report Function: micro_benchmark_clock_time micro_benchmark_exec_report_total_time (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned is the total time, including library overhead, spent on the test case execution associated to report.

C Report Function: size_t micro_benchmark_exec_report_total_samples (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned is the total number of samples collected by the test case execution associated to report.

C Report Function: size_t micro_benchmark_exec_report_used_samples (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned is the number of samples used for the statistical data aggregation of the test case execution associated to report.

C Report Function: micro_benchmark_stats_value micro_benchmark_exec_report_iteration_time (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned contains the statistical values calculated with regard of the time elapsed per iteration of the test case execution associated to report.

C Report Function: micro_benchmark_stats_value micro_benchmark_exec_report_sample_time (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned contains the statistical values calculated with regard of the sample time of the test case execution associated to report.

C Report Function: micro_benchmark_stats_value micro_benchmark_exec_report_sample_iterations (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned contains the statistical values calculated with regard of the iterations per sample of the test case execution associated to report.

The report can contain additional data collected during the test execution (see Custom Data Collection Reference.)

Note: This API is still on a very early stage, expect changes.

C Data Type: micro_benchmark_report_extra_data { const char*name, size_t size, const char **keys, const char**values } ¶

Additional data collected. name identifies the data. The length of keys and values must be greater or equal than size.

C Function Type: micro_benchmark_report_extractor_fun ¶

Extract a printable representation of the collected data. Its prototype is micro_benchmark_report_extra_data (*) (void *).

C Report Function: size_t micro_benchmark_exec_report_number_of_meters (micro_benchmark_exec_report report) ¶

Note: Not specified yet.

Return the number of custom meters whose data has been collected onto report.

C Report Function: size_t micro_benchmark_exec_report_meter_num_samples (micro_benchmark_exec_report report, size_t meter) ¶

Note: Not specified yet.

Return the number of samples collected by meter onto report. meter must be less than the value returned by micro_benchmark_exec_report_number_of_meters.

C Report Function: micro_benchmark_stats_sample_type micro_benchmark_exec_report_meter_sample_type (micro_benchmark_exec_report report, size_t meter) ¶

Note: Not specified yet.

Return the type of samples collected by meter onto report. meter must be less than the value returned by micro_benchmark_exec_report_number_of_meters.

C Report Function: micro_benchmark_stats_generic_sample micro_benchmark_exec_report_meter_get_sample (micro_benchmark_exec_report report, size_t meter, size_t pos) ¶

Note: Not specified yet.

Return the sample pos collected by meter onto report. meter must be less than the value returned by micro_benchmark_exec_report_number_of_meters (report) and pos must be less than the value returned by micro_benchmark_exec_report_meter_num_samples.

C Report Function: micro_benchmark_report_extra_data micro_benchmark_exec_report_get_extra_data (micro_benchmark_exec_report report, size_t pos) ¶

Note: Not specified yet.

Extract the custom data stored on report from meter pos.

4.4.4 Output Reference

This section documents the output of the reported data.

C Data Type: micro_benchmark_output_type { MICRO_BENCHMARK_CONSOLE_OUTPUT, MICRO_BENCHMARK_TEXT_OUTPUT, MICRO_BENCHMARK_LISP_OUTPUT } ¶

Predefined output formats:

• See Console Output for a more detailed description of the format produced by MICRO_BENCHMARK_CONSOLE_OUTPUT.
• See Text Output for a more detailed description of the format produced by MICRO_BENCHMARK_TEXT_OUTPUT.
• See Lisp Output for a more detailed description of the format produced by MICRO_BENCHMARK_LISP_OUTPUT.

C Data Type: micro_benchmark_output_stat { MICRO_BENCHMARK_STAT_NONE, MICRO_BENCHMARK_STAT_MEAN, MICRO_BENCHMARK_STAT_VARIANCE, MICRO_BENCHMARK_STAT_STD_DEVIATION, MICRO_BENCHMARK_STAT_BASIC, MICRO_BENCHMARK_STAT_ALL } ¶

Provided statistical values.

• The values can be joined with | to select both values.
• The value BASIC is equivalent to MEAN | STD_DEVIATION.
• The value ALL is is equivalent to MEAN | VARIANCE | STD_DEVIATION.

C Data Type: micro_benchmark_output_values { bool self_test, bool size_constraints, bool total_time, bool total_iterations, bool iterations, bool total_samples, bool samples, bool extra_data, micro_benchmark_output_stat iteration_times, micro_benchmark_output_stat sample_times, micro_benchmark_output_stat batch_stats } ¶

Each field determines the output of a value of the report.

C Report Function: micro_benchmark_output_values micro_benchmark_get_default_output_values () ¶

Preconditions:

1. No additional precondition.

Effects:

1. None.

Postconditions:

1. If micro_benchmark_set_default_output_values was called, the returned value is equivalent to the parameter provided to the last call in effect of micro_benchmark_set_default_output_values.

C Output Function: void micro_benchmark_set_default_output_values (micro_benchmark_output_values new_values) ¶

Preconditions:

1. No additional precondition.

Effects:

1. Change default output values.

Postconditions:

1. The output functions that do not accept a parameter of type micro_benchmark_output_values will use the values provided by new_values to the last call of this function.

C Output Function: void micro_benchmark_write_report (micro_benchmark_report report, FILE *out, micro_benchmark_output_type type) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.
2. out is ready to receive an indeterminate number of characters.

Effects:

1. Write the values from report determined by micro_benchmark_get_default_output_values on out with output format type.

Postconditions:

1. out has successfully received the formatted data stored on report.

C Output Function: void micro_benchmark_write_custom_report (micro_benchmark_report report, FILE *out, micro_benchmark_output_type type, const micro_benchmark_output_values *values) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.
2. out is ready to receive an indeterminate number of characters.

Effects:

1. Write the values from report determined by values on out with the output format type.

Postconditions:

1. out has successfully received the formatted data stored on report.

C Report Function: void micro_benchmark_print_report (micro_benchmark_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.
2. The standard output is ready to receive an indeterminate number of characters.

Effects:

1. Write the values from report determined by micro_benchmark_get_default_output_values on the standard output with the console format.

Postconditions:

1. The standard output has successfully received the formatted data stored on report.

C Output Function: void micro_benchmark_print_custom_report (micro_benchmark_report report, const micro_benchmark_output_values *values) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.
2. The standard output is ready to receive an indeterminate number of characters.

Effects:

1. Write the values from report determined by values on out with the console output format.

Postconditions:

1. The standard output has successfully received the formatted data stored on report.

4.5.1 Custom Data Collection Reference

C Function Type: micro_benchmark_custom_sample_create_data_fun ¶

Its prototype is void *(*) (void).

C Function Type: micro_benchmark_custom_sample_release_data_fun ¶

Its prototype is void (*) (void *);

C Function Type: micro_benchmark_custom_sample_collector_fun ¶

Its prototype is void (*) (void *, size_t, micro_benchmark_stats_generic_samples).

C Data Type: micro_benchmark_custom_sample_collector { micro_benchmark_custom_sample_create_data_fun create_data, micro_benchmark_custom_sample_release_data_fun release_data, micro_benchmark_custom_sample_collector_fun parse_samples, micro_benchmark_report_extractor_fun get_data } ¶

Custom data collection.

C Function Type: micro_benchmark_custom_time_calculator ¶

Its prototype is micro_benchmark_time_stats_values (*) (size_t, micro_benchmark_time_samples)

4.5.2 Meter Reference

A meter is an device that produces measurement samples.

Currently, the only meters provide by the library are chronometers (see Chronometer Reference.)

C Data Type: micro_benchmark_meter_data { void *ptr, const char *name, micro_benchmark_stats_sample_type sample_type, micro_benchmark_stats_meter_sample min_resolution, micro_benchmark_stats_meter_sample max_resolution } ¶

Data of a meter implementation.

ptr is the instance data that is provided to the meter functions. sample_type represents the active union field from the samples produced by the meter, as well as min_resolution and max_resolution fields.

C Function Type: micro_benchmark_meter_init_fun ¶

Function to initialize a meter instance. Its prototype is void (*) (micro_benchmark_meter_data *, const void *).

C Function Type: micro_benchmark_meter_cleanup_fun ¶

Function to release a meter instance. Its prototype is void (*) (const micro_benchmark_meter_data *).

C Function Type: micro_benchmark_meter_start_fun ¶

Start the measuring process of a meter instance. Its prototype is void (*) (void *).

C Function Type: micro_benchmark_meter_stop_fun ¶

Stop the measuring process of a meter instance. Its prototype is void (*) (void *).

C Function Type: micro_benchmark_meter_restart_fun ¶

Restart the measuring process of a meter instance. Its prototype is void (*) (void *).

C Function Type: micro_benchmark_meter_get_sample_fun ¶

Extract the measure performed by the meter. Its prototype is micro_benchmark_stats_meter_sample (*) (void *).

C Data Type: micro_benchmark_meter_definition { micro_benchmark_meter_data data, micro_benchmark_meter_init_fun init, micro_benchmark_meter_cleanup_fun cleanup, micro_benchmark_meter_start_fun start, micro_benchmark_meter_stop_fun stop, micro_benchmark_meter_restart_fun restart, micro_benchmark_meter_get_sample_fun get_sample } ¶

Meter definition.

C Data Type: micro_benchmark_meter ¶

Pointer to a constant micro_benchmark_meter_definition object.

C Meter Function: void micro_benchmark_stats_meter_init (micro_benchmark_meter_definition *meter) ¶

Preconditions:

1. meter points to a valid object.
2. meter->init points to a valid function.
3. The value meter is not valid. This means one of the following conditions:
   • No value equivalent to meter has been provided as a parameter to micro_benchmark_stats_meter_init or micro_benchmark_stats_meter_init_with_data.
   • Each call to micro_benchmark_stats_meter_init or micro_benchmark_stats_meter_init_with_data with a value equivalent to meter as its parameter has been followed by a call to micro_benchmark_stats_meter_cleanup with a value equivalent to meter as its parameter.

Effects:

1. Call meter->init (meter->data, NULL).

Postconditions:

1. The value meter is valid.

C Meter Function: void micro_benchmark_stats_meter_init_with_data (micro_benchmark_meter_definition *meter, const void *extra_data) ¶

Preconditions:

1. meter points to a valid object.
2. meter->init points to a valid function.
3. The value meter is not valid. This means one of the following conditions:
   • The value meter has not been provided as a parameter to micro_benchmark_stats_meter_init or micro_benchmark_stats_meter_init_with_data.
   • Each call to micro_benchmark_stats_meter_init or micro_benchmark_stats_meter_init_with_data with the value of meter as its parameter has been followed by a call to micro_benchmark_stats_meter_cleanup with the value of meter as its parameter.

Effects:

1. Call meter->init (meter->data, extra_data).

Postconditions:

1. The value meter is valid.

C Meter Function: void micro_benchmark_stats_meter_cleanup (micro_benchmark_meter meter) ¶

Preconditions:

1. meter points to a valid object.
2. meter->cleanup points to a valid function.
3. The value meter is valid.

Effects:

1. Call meter->cleanup.

Postconditions:

1. The value meter is not valid.

C Meter Function: void micro_benchmark_stats_meter_start (micro_benchmark_meter meter) ¶

Preconditions:

1. meter points to a valid object.
2. meter->start points to a valid function.
3. The value meter is valid.
4. meter is not measuring.

Effects:

1. Call meter->start.

Postconditions:

1. meter is running.
2. meter is measuring.
3. The measurements performed by meter take this call as its starting point.

C Meter Function: void micro_benchmark_stats_meter_stop (micro_benchmark_meter meter) ¶

Preconditions:

1. meter points to a valid object.
2. meter->stop points to a valid function.
3. The value meter is valid.
4. meter is running.
5. meter is measuring.

Effects:

1. Call meter->stop.

Postconditions:

1. meter is not measuring.
2. The measurements performed by meter take this call as its end point.

C Meter Function: void micro_benchmark_stats_meter_restart (micro_benchmark_meter meter) ¶

Preconditions:

1. meter points to a valid object.
2. meter->restart points to a valid function.
3. The value meter is valid.
4. meter is running.
5. meter is not measuring.

Effects:

1. Call meter->restart.

Postconditions:

1. meter is measuring.
2. The measurements performed by meter take this call as another starting point.

C Meter Function: micro_benchmark_stats_meter_sample micro_benchmark_stats_meter_get_sample (micro_benchmark_meter meter) ¶

Preconditions:

1. meter points to a valid object.
2. The value meter is valid.
3. meter is running.
4. meter is not measuring.

Effects:

1. Call meter->get_sample.

Postconditions:

1. The returned value contains the accumulated measurement performed by the value meter.
2. The accumulated measurement of meter is reset to zero its zero point—equivalent to a call to micro_benchmark_meter_start.

C Meter Function: const char * micro_benchmark_stats_meter_get_name (micro_benchmark_meter meter) ¶

Preconditions:

1. meter points to a valid object.
2. The value meter is valid.

Effects:

1. None.

Postconditions:

1. The returned value is meter->data.name;

C Meter Function: micro_benchmark_stats_sample_type micro_benchmark_stats_meter_get_sample_type (micro_benchmark_meter meter) ¶

Preconditions:

1. meter points to a valid object.
2. The value meter is valid.

Effects:

1. None.

Postconditions:

1. The returned value is meter->data.sample_type;

C Meter Function: micro_benchmark_stats_meter_sample micro_benchmark_stats_meter_get_min_resolution (micro_benchmark_meter meter) ¶

Preconditions:

1. meter points to a valid object.
2. The value meter is valid.

Effects:

1. None.

Postconditions:

1. The returned value is meter->data.min_resolution;

C Meter Function: micro_benchmark_stats_meter_sample micro_benchmark_stats_meter_get_max_resolution (micro_benchmark_meter meter) ¶

Preconditions:

1. meter points to a valid object.
2. meter->stop points to a valid function.
3. The value meter is valid.

Effects:

1. None.

Postconditions:

1. The returned value is meter->data.max_resolution;

4.5.3 Time Reference

C Data Type: micro_benchmark_clock_time { int32_t seconds, ¶

int32_t nanoseconds }

Structure used by the framework for time measuring.

C Data Type: micro_benchmark_clock_type { MICRO_BENCHMARK_CLOCK_REALTIME, MICRO_BENCHMARK_CLOCK_MONOTONIC, MICRO_BENCHMARK_CLOCK_PROCESS, MICRO_BENCHMARK_CLOCK_THREAD } ¶

Clock type enumeration (see Predefined Clocks.)

C Data Type: micro_benchmark_time_sample_ { bool discarded, size_t iterations, micro_benchmark_clock_time elapsed } ¶

Time sample value. This data type contains, at least, the specified values discarded, iterations and elapsed.

C Data Type: micro_benchmark_time_sample ¶

Pointer to a constant value of type micro_benchmark_time_sample_.

C Data Type: micro_benchmark_time_samples ¶

Pointer to an array of constant values of type micro_benchmark_time_sample_ values. This type is equivalent to micro_benchmark_time_sample and it is used only for documentation purposes.

C Data Type: micro_benchmark_stats_unit { MICRO_BENCHMARK_STATS_UNIT_NONE, MICRO_BENCHMARK_STATS_ITERATIONS, MICRO_BENCHMARK_STATS_TIME_MIN, MICRO_BENCHMARK_STATS_TIME_S, MICRO_BENCHMARK_STATS_TIME_MS, MICRO_BENCHMARK_STATS_TIME_US, MICRO_BENCHMARK_STATS_TIME_NS } ¶

Unit of measure.

C Data Type: micro_benchmark_stats_value { micro_benchmark_stats_unit unit, double mean, double variance, double std_deviation } ¶

Aggregated statistical values.

C Data Type: micro_benchmark_time_stats_values { size_t total_samples, size_t samples, size_t iterations, micro_benchmark_stats_value iteration_time, micro_benchmark_stats_value sample_time, micro_benchmark_stats_value sample_iterations } ¶

Information sampled during a test case execution.

Note: this type is experimental.

4.5.4 Chronometer Reference

A chronometer is a specialization of a meter that measures time duration.

C Data Type: micro_benchmark_chronometer_provider { MICRO_BENCHMARK_CHRONO_PROVIDER_DEFAULT, MICRO_BENCHMARK_CHRONO_PROVIDER_TIME_T, MICRO_BENCHMARK_CHRONO_PROVIDER_CLOCK_T, MICRO_BENCHMARK_CHRONO_PROVIDER_GETTIMEOFDAY, MICRO_BENCHMARK_CHRONO_PROVIDER_CLOCK_GETTIME, MICRO_BENCHMARK_CHRONO_PROVIDER_USER_PROVIDED } ¶

Chronometer type (see Predefined Chronometers.)

C Chronometer Function: micro_benchmark_meter micro_benchmark_chronometer_create_default () ¶

Preconditions:

1. None.

Effects:

1. Allocate and initialize a new chronometer.

Postconditions:

1. The returned value meter is a valid chronometer.
2. If micro_benchmark_chronometer_set_default was called, the type of the returned value is equivalent to the last value provided to that call.

C Chronometer Function: micro_benchmark_meter micro_benchmark_chronometer_create (micro_benchmark_clock_type clock_type, micro_benchmark_chronometer_provider provider) ¶

Preconditions:

1. clock_type is implemented by this system.
2. provider is not equal to MICRO_BENCHMARK_CHRONO_PROVIDER_USER_PROVIDED.
3. provider support is implemented by the library.
4. clock_type is implemented by provider.

Effects:

1. Allocate and initialize a new chronometer of type provider using the clock type clock_type.

Postconditions:

1. The returned value is a valid chronometer.

C Chronometer Function: micro_benchmark_meter micro_benchmark_chronometer_from_meter (micro_benchmark_clock_type clock_type, micro_benchmark_meter base) ¶

Preconditions:

1. clock_type is implemented by this system.
2. Either:
   • base points to a valid chronometer.
   • base points to an object of type micro_benchmark_meter_definition where at least all the function fields have been filled with a valid function.
   • clock_type is implemented by base.

Effects:

1. Allocate a new chronometer ptr.
2. Copy the data pointed by base to ptr.
3. Initialize the allocated chronometer with micro_benchmark_stats_meter_init_with_data (ptr, clock_type)

Postconditions:

1. The returned value is a valid chronometer.

C Chronometer Function: void micro_benchmark_chronometer_release (micro_benchmark_meter meter) ¶

Preconditions:

1. meter is a valid chronometer.

Effects:

1. Cleanup and release meter.

Postconditions:

1. The value meter is not valid.

C Chronometer Function: void micro_benchmark_chronometer_set_default (micro_benchmark_meter meter) ¶

Preconditions:

1. Either:
   • base points to a valid chronometer.
   • base points to an object of type micro_benchmark_meter_definition where at least all the field function fields have been filled with a valid function.

Effects:

1. A copy of meter is stored.

Postconditions:

1. The chronometers created providing the enumeration constant MICRO_BENCHMARK_CHRONO_PROVIDER_DEFAULT to micro_benchmark_chronometer_create will have the same effective type as the meter provided to the last call of this function.

C Chronometer Function: micro_benchmark_meter micro_benchmark_chronometer_get_default () ¶

Preconditions:

1. None.

Effects:

1. None.

Postconditions:

1. The returned value is the effective type of the chronometers created providing the enumeration constant MICRO_BENCHMARK_CHRONO_PROVIDER_DEFAULT.
2. If micro_benchmark_chronometer_set_default was called, the returned value is equivalent to the last value provided to that call.

4.6.1 Timer Provider Reference

C Data Type: micro_benchmark_timer_provider { MICRO_BENCHMARK_TIMER_PROVIDER_DEFAULT, MICRO_BENCHMARK_TIMER_PROVIDER_ITIMER, MICRO_BENCHMARK_TIMER_PROVIDER_TIMER_T, MICRO_BENCHMARK_TIMER_PROVIDER_TIMERFD, MICRO_BENCHMARK_TIMER_PROVIDER_FROM_METER, MICRO_BENCHMARK_TIMER_PROVIDER_USER_PROVIDED } ¶

Timer type (see Predefined Timers.)

C Timer Function: micro_benchmark_timer micro_benchmark_timer_create_default () ¶

Preconditions:

1. None.

Effects:

1. Allocate and initialize a new timer of the default type.

Postconditions:

1. The returned value timer is a valid chronometer.
2. If micro_benchmark_timer_set_default was called, the type of the returned value is equivalent to the last value provided to that call.

C Timer Function: micro_benchmark_timer micro_benchmark_timer_create (micro_benchmark_clock_type clock_type, micro_benchmark_timer_provider provider) ¶

Preconditions:

1. clock_type is implemented by this system.
2. provider is not equal to MICRO_BENCHMARK_TIMER_PROVIDER_USER_PROVIDED.
3. provider is not equal to MICRO_BENCHMARK_TIMER_PROVIDER_FROM_METER.
4. provider support is implemented by the library.
5. clock_type is implemented by provider.

Effects:

1. Allocate and initialize a new timer of type provider using the clock type clock_type.

Postconditions:

1. The returned value is a valid timer.

C Timer Function: micro_benchmark_timer micro_benchmark_timer_from_meter (micro_benchmark_clock_type clock_type, micro_benchmark_chronometer_provider chrono_provider) ¶

Preconditions:

1. clock_type is implemented by this system.
2. chrono_provider is implemented by this system.

Effects:

1. Allocate a new chronometer adapter ptr of type chrono_provider.
2. Initialize the allocated timer.

Postconditions:

1. The returned value is a valid chronometer.

C Timer Function: micro_benchmark_timer micro_benchmark_timer_from_provided_meter (micro_benchmark_clock_type clock_type, micro_benchmark_meter chrono_base) ¶

Preconditions:

1. clock_type is implemented by this system.
2. Either:
   • chrono_base points to a valid chronometer.
   • chrono_base points to an object of type micro_benchmark_meter_definition where at least all the function fields have been filled with a valid function.
   • clock_type is implemented by chrono_base.

Effects:

1. Allocate a new chronometer adapter ptr with the same type as base.
2. Initialize the allocated timer.

Postconditions:

1. The returned value is a valid chronometer.

C Timer Function: micro_benchmark_timer micro_benchmark_timer_from_template (micro_benchmark_clock_type clock_type, micro_benchmark_meter base) ¶

Preconditions:

1. clock_type is implemented by this system.
2. Either:
   • base points to a valid timer.
   • base points to an object of type micro_benchmark_timer_definition where at least all the function fields have been filled with a valid function.
   • clock_type is implemented by base.

Effects:

1. Allocate a new timer ptr.
2. Copy base contents to ptr.
3. Initialize ptr

Postconditions:

1. The returned value is a valid chronometer.

C Timer Function: void micro_benchmark_timer_release (micro_benchmark_timer timer) ¶

Preconditions:

1. timer is a valid timer.

Effects:

1. Cleanup and release timer.

Postconditions:

1. The value timer is not valid.

4.7.1 Library Log Reference

The library produce messages at different levels of verbosity.

C Data Type: micro_benchmark_log_level { MICRO_BENCHMARK_ERROR_LEVEL, MICRO_BENCHMARK_WARNING_LEVEL, MICRO_BENCHMARK_INFO_LEVEL, MICRO_BENCHMARK_DEBUG_LEVEL, MICRO_BENCHMARK_TRACE_LEVEL } ¶

Levels used by the library (see Configuration).

The following functions control the logging output generated by the library:

C Log Function: void micro_benchmark_log_set_output (FILE *out) ¶

Preconditions:

1. out is a valid FILE.

Effects:

1. Use out to emit log messages.

Postconditions:

1. out will receive the log messages emitted by the library up to the next call to micro_benchmark_log_set_output or micro_benchmark_log_reset_output.

C Log Function: void micro_benchmark_log_reset_output () ¶

Preconditions:

1. None.

Effects:

1. If micro_benchmark_log_set_output was called, stop using the provided FILE *.
2. Use the default output to emit log messages.

Postconditions:

1. The default output will receive the log messages emitted by the library up to the next call to micro_benchmark_log_set_output.

C Log Function: void micro_benchmark_set_log_level (micro_benchmark_log_level level) ¶

Preconditions:

1. level is valid.

Effects:

1. Set the log level to level.

Postconditions:

1. The library won’t emit messages with less severity than level up to the next call to micro_benchmark_set_log_level.

C Log Function: void micro_benchmark_set_module_log_level (const char *module, micro_benchmark_log_level level) ¶

Preconditions:

1. level is valid.
2. module points to a valid, zero-ended array of characters.

Effects:

1. Set the log level for module to level.

Postconditions:

1. The library won’t emit messages of module with less severity than level up to the next call to micro_benchmark_set_log_level.

4.7.2 Optimization Utilities Reference

The following macros are meant to avoid certain optimizations the compiler might perform on your test code.

C Optimization Macro: MICRO_BENCHMARK_DO_NOT_OPTIMIZE (lvalue) ¶

Preconditions:

1. Function scope macro.

Effects:

1. Simulate read+write on lvalue.

Postconditions:

1. The compiler should not optimize lvalue away.

C Optimization Macro: MICRO_BENCHMARK_COMPILER_BARRIER () ¶

Preconditions:

1. Function scope macro.

Effects:

1. Memory fence.

Postconditions:

1. The compiler should treat all memory as clobbered.

C Utility Function: void micro_benchmark_do_not_optimize (const void *dummy) ¶

Preconditions:

1. None.

Effects:

1. “Compatibility” implementation of the previous macros.

Postconditions:

1. A wish of hope and not much more.