Benchmark
Eina » Tools

These functions allow you to add a benchmark framework to a project for timing critical parts and detecting slow parts of code. More...

## Macros

#define | EINA_BENCHMARK(function)
| Definition for the cast to an Eina_Benchmark_Specimens.

## Typedefs

typedef struct _Eina_Benchmark | Eina_Benchmark
| Type for a benchmark.
typedef void(* | Eina_Benchmark_Specimens) (int request)
| Type for a test function to be called when running a benchmark.

## Functions

EINA_API Eina_Benchmark * | eina_benchmark_new (const char *name, const char *run)
| Creates a new array.
EINA_API void | eina_benchmark_free (Eina_Benchmark *bench)
| Frees a benchmark object.
EINA_API Eina_Bool | eina_benchmark_register (Eina_Benchmark *bench, const char *name, Eina_Benchmark_Specimens bench_cb, int count_start, int count_end, int count_step)
| Adds a test to a benchmark.
EINA_API Eina_Array * | eina_benchmark_run (Eina_Benchmark *bench)
| Runs the benchmark's registered tests.

## Detailed Description

These functions allow you to add a benchmark framework to a project for timing critical parts and detecting slow parts of code.

It is used in Eina to compare the time used by eina, glib, evas and ecore data types.

To use the benchmark module, Eina must be initialized with eina_init() and later shut down with eina_shutdown(). A benchmark is created with eina_benchmark_new() and freed with eina_benchmark_free().

eina_benchmark_register() adds a test to a benchmark. That test can be run a certain amount of times. Adding more than one test to be executed allows the comparison between several parts of a program, or different implementations.

eina_benchmark_run() runs all the tests registered with eina_benchmark_register(). The amount of time of each test is written in a gnuplot file.

For more information, you can look at the Benchmark Tutorial.

## Macro Definition Documentation

## EINA_BENCHMARK

#define EINA_BENCHMARK | ( |  | function | ) |

Value:
((Eina_Benchmark_Specimens)function)
Eina_Benchmark_Specimens
void(* Eina_Benchmark_Specimens)(int request)
Type for a test function to be called when running a benchmark.
Definition eina_benchmark.h:335

Definition for the cast to an Eina_Benchmark_Specimens.

Parameters

  [in] | function | The function to cast.

This macro casts `function` to Eina_Benchmark_Specimens.

## Function Documentation

## eina_benchmark_new()

EINA_API Eina_Benchmark * eina_benchmark_new | ( | const char * | name,
|  | const char * | run )

Creates a new array.

Parameters

  [in] | name | The name of the benchmark.
  [in] | run | The name of the run.

Returns
  A valid benchmark on success, or `NULL` on memory allocation failure.

This function creates a new benchmark. `name` and `run` are used to name the gnuplot file that eina_benchmark_run() will create.

When the new module is not needed anymore, use eina_benchmark_free() to free the allocated memory.

## eina_benchmark_free()

EINA_API void eina_benchmark_free | ( | Eina_Benchmark * | bench | ) |

Frees a benchmark object.

Parameters

  [in,out] | bench | The benchmark to free.

This function removes all the benchmark tests that have been registered and frees `bench`. If `bench` is `NULL`, this function returns immediately.

References eina_array_free(), EINA_ARRAY_ITER_NEXT, eina_inlist_remove(), and EINA_LIST_FREE.

## eina_benchmark_register()

EINA_API Eina_Bool eina_benchmark_register | ( | Eina_Benchmark * | bench,
|  | const char * | name,
|  | Eina_Benchmark_Specimens | bench_cb,
|  | int | count_start,
|  | int | count_end,
|  | int | count_step )

Adds a test to a benchmark.

Parameters

  [in,out] | bench | The benchmark.
  [in] | name | The name of the test.
  [in] | bench_cb | The test function to be called.
  [in] | count_start | The start data to be passed to `bench_cb`.
  [in] | count_end | The end data to be passed to `bench_cb`.
  [in] | count_step | The step data to be passed to `bench_cb`.

Returns
  EINA_FALSE on failure, EINA_TRUE otherwise.

This function adds the test named `name` to `benchmark`. `bench_cb` is the function called when the test is executed. That test can be executed a certain number of times, from `count_start` to `count_end`, with a step increment of `count_step`. This counter is passed to `bench_cb` when eina_benchmark_run() is called.

If `bench` is `NULL` or `count_step` is 0, this function returns immediately and does not add any tests to the benchmark.

References EINA_FALSE, eina_inlist_append(), EINA_INLIST_GET, and EINA_TRUE.

## eina_benchmark_run()

EINA_API Eina_Array * eina_benchmark_run | ( | Eina_Benchmark * | bench | ) |

Runs the benchmark's registered tests.

Parameters

  [in,out] | bench | The benchmark.

Returns
  A list of gnuplot filenames for the test results, or `NULL` on failure.

This function runs all the tests that have been registered with eina_benchmark_register() and saves the result in gnuplot input files. The filenames have the following format:

bench_[name]_[run]%s.gnuplot

Where [name] and [run] are the values passed to eina_benchmark_new() when registering the test.

Each registered test is executed and timed. The time is written to the gnuplot file. The number of times each test is executed is controlled by the parameters passed to eina_benchmark_register().

References alloca(), eina_array_new(), eina_array_push(), eina_counter_dump(), eina_counter_free(), eina_counter_new(), eina_counter_start(), eina_counter_stop(), EINA_FALSE, EINA_INLIST_FOREACH, eina_list_append(), eina_strbuf_append(), eina_strbuf_free(), eina_strbuf_new(), eina_strbuf_replace_all(), eina_strbuf_string_get(), and EINA_TRUE.