---

4.3 State Reference

Note: the lifetime of test state objects is semantically bound to the call where it is received as parameter. Once the scope of the function call ends, the object is not considered valid anymore³ and any usage of its value is undefined.

C Data Type: micro_benchmark_test_state ¶

Opaque type, representation of the internal state of the test execution.

The following function is the main driver of the benchmark. It performs the data collection and determines if the test code must be executed again.

C Test State Function: bool micro_benchmark_state_keep_running (micro_benchmark_test_state state) ¶

Preconditions:

1. state is a valid object.

Effects:

1. Performance measurements are performed and stored on state.

Postconditions:

1. The returned value is true if the test should perform at least one iteration more according to its constraints.

C Test State Function: size_t micro_benchmark_state_get_dimensions (micro_benchmark_test_state state) ¶

Preconditions:

1. state is a valid object.

Effects:

1. None.

Postconditions:

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

C Test State Function: size_t micro_benchmark_state_get_size (micro_benchmark_test_state state, size_t dimension) ¶

Preconditions:

1. state is a valid object.

Effects:

1. None.

Postconditions:

1. If micro_benchmark_test_case_add_dimension was called at least dimension+1 times, the returned value is one of the values provided  call number dimension, starting from 0, to micro_benchmark_test_case_add_dimension to the test associated to state.
2. The value returned is zero when micro_benchmark_test_case_add_dimension was called less than dimension+1 times.

C Test State Function: void * micro_benchmark_state_get_data (micro_benchmark_test_state state) ¶

Preconditions:

1. state is a valid object.

Effects:

1. None.

Postconditions:

1. During the set up stage, the value returned is NULL unless micro_benchmark_test_case_set_data was called. In the latter case, the value of the object pointer provided to micro_benchmark_test_case_set_data is returned.
2. During the tear down and test stages, the value returned is undefined unless micro_benchmark_test_case_set_data was called. In the latter case, the value of the object pointer provided to micro_benchmark_test_case_set_data is returned.

C Test State Function: void micro_benchmark_state_set_name (micro_benchmark_test_state state, const char *name) ¶

Preconditions:

1. state is a valid object.
2. name must point to a valid, zero-ended array of characters.

Effects:

1. A disjoint copy of the characters pointed by name is stored by state.

Postconditions:

1. The last value provided to this call is used as name for the test execution report of the execution associated to state.

C Test State Function: const char * micro_benchmark_state_get_name (micro_benchmark_test_state state) ¶

Preconditions:

1. state is a valid object.

Effects:

1. None.

Postconditions:

1. The value returned points to a valid, zero-ended array of characters.
2. If micro_benchmark_state_set_name was called, the value returned is equivalent to the value provided to micro_benchmark_state_set_name.
3. If micro_benchmark_state_set_name was not called, the value returned is equivalent to the value provided to micro_benchmark_suite_register_test.