Previous: , Up: C API Reference   [Contents][Index]

4.7 Utilities Reference

The following function can be used to provide a custom error handler to be executed by the library if any postcondition, implicit or explicit, could not be provided:

C Error Function: void micro_benchmark_set_error_handler (void (*handler) (void))

Preconditions:

  1. The function pointed by handler does not return, neither through a return statement or the end of its scope, nor non-locally such as a longjmp call.

Effects:

  1. Store handler, forgetting any previous value provided.

Postconditions:

  1. handler will be called if a postcondition could not be provided.


These are some utilities to make quick and easy a test with MicroBenchmark.

C Utility Macro: MICRO_BENCHMARK_REGISTER_TEST (fun)

Preconditions:

  1. File scope macro.
  2. fun type is (or decays to) micro_benchmark_test_fun.

Effects:

  1. Register the directed test fun.
  2. Use #fun as the test registration name.

Postconditions:

  1. The test will be executed by micro_benchmark_main unless its execution is disabled by its parameters or the provided test constraints.


C Utility Macro: MICRO_BENCHMARK_REGISTER_FULL_TEST (setup, fun, teardown)

Preconditions:

  1. File scope macro.
  2. setup type is (or decays to) micro_benchmark_set_up_fun.
  3. fun type is (or decays to) micro_benchmark_test_fun.
  4. teardown type is (or decays to) micro_benchmark_set_up_fun.

Effects:

  1. Register the directed test fun, calling setup before each run of fun, and calling teardown after each run.
  2. Use #fun as the test registration name.

Postconditions:

  1. The test will be executed by micro_benchmark_main unless its execution is disabled by its parameters or the provided test constraints.


C Utility Macro: MICRO_BENCHMARK_REGISTER_NAMED_TEST (name, setup, test, teardown)

Preconditions:

  1. File scope macro.
  2. The type of name is (or decays to) const char *, and points to a valid, zero-ended array of characters.
  3. setup type is (or decays to) micro_benchmark_set_up_fun.
  4. fun type is (or decays to) micro_benchmark_test_fun.
  5. teardown type is (or decays to) micro_benchmark_set_up_fun.

Effects:

  1. Register the directed test fun, calling setup before each run of fun, and calling teardown after each run.
  2. Use name as the test registration name.

Postconditions:

  1. The test will be executed by micro_benchmark_main unless its execution is disabled by its parameters or the provided test constraints.


C Utility Macro: MICRO_BENCHMARK_REGISTER_SIMPLE_TEST (fun)

Preconditions:

  1. File scope macro.
  2. fun type is (or decays to) micro_benchmark_auto_test_fun.

Effects:

  1. Register the automatic test fun.
  2. Use #fun as the test registration name.

Postconditions:

  1. The test will be executed by micro_benchmark_main unless its execution is disabled by its parameters or the provided test constraints.


C Utility Macro: MICRO_BENCHMARK_REGISTER_AUTO_TEST (setup, fun, teardown)

Preconditions:

  1. File scope macro.
  2. setup type is (or decays to) micro_benchmark_set_up_fun.
  3. fun type is (or decays to) micro_benchmark_auto_test_fun.
  4. teardown type is (or decays to) micro_benchmark_set_up_fun.

Effects:

  1. Register the automatic test fun, calling setup before each run of fun, and calling teardown after each run.
  2. Use #fun as the test registration name.

Postconditions:

  1. The test will be executed by micro_benchmark_main unless its execution is disabled by its parameters or the provided test constraints.


C Utility Macro: MICRO_BENCHMARK_REGISTER_NAMED_AUTO_TEST (name, setup, test, teardown)

Preconditions:

  1. File scope macro.
  2. The type of name is (or decays to) const char *, and points to a valid, zero-ended array of characters.
  3. setup type is (or decays to) micro_benchmark_set_up_fun.
  4. fun type is (or decays to) micro_benchmark_auto_test_fun.
  5. teardown type is (or decays to) micro_benchmark_set_up_fun.

Effects:

  1. Register the automatic test fun, calling setup before each run of fun, and calling teardown after each run.
  2. Use name as the test registration name.

Postconditions:

  1. The test will be executed by micro_benchmark_main unless its execution is disabled by its parameters or the provided test constraints.


C Function Type: micro_benchmark_static_constraint

Its prototype is void (*) (micro_benchmark_test_case).


C Utility Macro: MICRO_BENCHMARK_CONSTRAINT_TEST (name, fun)

Preconditions:

  1. File scope macro.
  2. The type of name is (or decays to) const char *, and points to a valid, zero-ended array of characters.
  3. fun type is (or decays to) micro_benchmark_static_constraint.

Effects:

  1. Register the constraint fun.

Postconditions:

  1. fun will be called with the test named name as its parameter by micro_benchmark_main, if a test with that name has been registered.


C Utility Macro: MICRO_BENCHMARK_MAIN ()

Preconditions:

  1. File scope macro.
  2. int main (int, char**) is not defined elsewhere on the binary.

Effects:

  1. Define int main (int, char **).

Postconditions:

  1. The resulting binary will call micro_benchmark_main with the provided command line arguments its value to the main function.


C Utility Function: void micro_benchmark_main (int argc, char **argv)

Preconditions:

  1. argc is a non positive integer.
  2. argv points to an array of char *.
  3. argc is less or equal to the number of elements pointed by argv.
  4. Each value pointed by argv either is NULL or points to a valid, readable, zero-ended array of characters.

Effects:

  1. Parse the command line:
  2. If argv contains the parameters --help, --version or an unrecognized parameter, call exit with the corresponding value.
  3. Execute the registered tests.
  4. Print the results.

Postconditions:

  1. The standard output, or the output file provided through the command line parameters, was flushed.
  2. The value returned is EXIT_SUCCESS.


The following functions are used to implement the registration macros:

C Utility Function: void micro_benchmark_register_static_test (const char *name, micro_benchmark_test test)

Preconditions:

  1. name must point to a valid, zero-ended array of characters.
  2. test must point to a valid test definition.

Effects:

  1. Register test as name.

Postconditions:

  1. micro_benchmark_main will execute test unless it is disabled through its parameters or the constraints associated to name.


C Utility Function: void micro_benchmark_register_static_constraint (const char *name, micro_benchmark_static_constraint constraint)

Preconditions:

  1. name must point to a valid, zero-ended array of characters.
  2. constraint must point to a valid function.

Effects:

  1. Register constraints for name.

Postconditions:

  1. micro_benchmark_main will call constraint if a test was registered as name as its parameter, with the test case as its parameter.


NOTE: The following functions are executed automatically by the linker on all known configurations. Do not call them manually.

C Utility Function: void micro_benchmark_init ()

Preconditions:

  1. Either:
    • micro_benchmark_init has not been called before.
    • Each call to micro_benchmark_init has been followed by a corresponding call to micro_benchmark_cleanup.

Effects:

  1. Configure message translations when the library was built with Native Language Support (see Configuration).
  2. Configure Logging output.

Postconditions:

  1. Messages are printed on the user localization, when this is available.


C Utility Function: void micro_benchmark_cleanup ()

Preconditions:

  1. Either:
    • micro_benchmark_init has been called once.
    • Every call to micro_benchmark_init except the last one has been followed by a corresponding call to micro_benchmark_cleanup.

Effects:

  1. Cleanup internal data.

Postconditions:

  1. The registered tests are not executed by a call to micro_benchmark_main anymore.


Previous: Timer Reference, Up: C API Reference   [Contents][Index]