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
====================================