---

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;