---

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.