Counter

Typedefs | Functions
Counter
Eina » Tools

This group discusses the functions that allow you to get the time spent in a part of a code. More...

## Typedefs
typedef struct _Eina_Counter | Eina_Counter
| An opaque type for counter.

## Functions
EAPI Eina_Counter * | eina_counter_new (const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1)
| Returns a counter. More...
EAPI void | eina_counter_free (Eina_Counter *counter) EINA_ARG_NONNULL(1)
| Deletes a counter. More...
EAPI void | eina_counter_start (Eina_Counter *counter) EINA_ARG_NONNULL(1)
| Starts the time count. More...
EAPI void | eina_counter_stop (Eina_Counter *counter, int specimen) EINA_ARG_NONNULL(1)
| Stops the time count. More...
EAPI char * | eina_counter_dump (Eina_Counter *counter) EINA_ARG_NONNULL(1)
| Dumps the result of all the clocks of a counter to a stream. More...

## Detailed Description

This group discusses the functions that allow you to get the time spent in a part of a code.

Before using the counter system, Eina must be initialized with eina_init() and later shut down with eina_shutdown(). To create a counter, use eina_counter_new(). To free it, use eina_counter_free().

To time a part of a code, call eina_counter_start() just before it, and eina_counter_stop() just after it. Each time you start to time a code, a clock is added to a list. You can give the number of that clock with the second argument of eina_counter_stop(). To send all the registered clocks to a stream (like stdout, for a file), use eina_counter_dump().

Here is a straightforward example:

#include <stdlib.h>
#include <stdio.h>
#include <eina_counter.h>
void test_malloc(void)
{
int i;
for (i = 0; i < 100000; ++i)
{
void *buf;
buf = malloc(100);
free(buf);
}
}
int main(void)
{
Eina_Counter *counter;
if (!eina_init())
{
printf("Error during the initialization of eina\n");
return EXIT_FAILURE;
}
counter = eina_counter_new("malloc");
eina_counter_start(counter);
test_malloc();
eina_counter_stop(counter, 1);
char* result = eina_counter_dump(counter);
printf("%s", result);
free(result);
eina_counter_free(counter);
eina_shutdown();
return EXIT_SUCCESS;
}

Compile this code with the following command:

    * gcc -Wall -o test_eina_counter test_eina.c `pkg-config --cflags --libs eina`
    *

The result should be something like this:

    * \# specimen    experiment time    starting time    ending time
    * 1              9794125            783816           10577941
    *

Note
  The displayed time is in nanoseconds.

## Function Documentation

## ◆ eina_counter_new()

EAPI Eina_Counter* eina_counter_new | ( | const char * | name | ) |

Returns a counter.

Parameters

  [in] | name | The name of the counter

Returns
  A newly allocated counter

This function returns a new counter. It is characterized by `name`. If `name` is `NULL`, the function returns `NULL` immediately. If memory allocation fails, `NULL` is returned.

Note
  Whe the new counter is not needed anymore, use eina_counter_free() to free the allocated memory.

Referenced by eina_benchmark_run().

## ◆ eina_counter_free()

EAPI void eina_counter_free | ( | Eina_Counter * | counter | ) |

Deletes a counter.

Parameters

  [in] | counter | The counter to delete

This function removes the clock of `counter` from the used clocks (see eina_counter_start()) and frees the memory allocated for `counter`. If `counter` is `NULL`, the function returns immediately.

Referenced by eina_benchmark_run().

## ◆ eina_counter_start()

EAPI void eina_counter_start | ( | Eina_Counter * | counter | ) |

Starts the time count.

Parameters

  [in] | counter | The counter

This function specifies that the part of the code beginning just after its call is being timed, using `counter`. If `counter` is `NULL`, this function returns immediately.

Note
  This function adds the clock associated to `counter` in a list. If the memory needed by that clock can not be allocated, the function returns and nothing is done.
  To stop the timing, eina_counter_stop() must be called with the same counter.

Referenced by eina_benchmark_run().

## ◆ eina_counter_stop()

EAPI void eina_counter_stop | ( | Eina_Counter * | counter,
|  | int | specimen
| ) |  |

Stops the time count.

Parameters

  [in] | counter | The counter
  [in] | specimen | The number of the test

This function stops the timing that has been started with eina_counter_start(). `counter` must be the same as the one used with eina_counter_start(). `specimen` is the number of the test. If `counter` or its associated clock is `NULL`, or if the time can't be retrieved the function exits.

Referenced by eina_benchmark_run().

## ◆ eina_counter_dump()

EAPI char* eina_counter_dump | ( | Eina_Counter * | counter | ) |

Dumps the result of all the clocks of a counter to a stream.

Parameters

  [in] | counter | The counter

Returns
  A string with a summary of the test

This function returns an malloc'd string containing the dump of all the valid clocks of `counter`. If `counter` is `NULL`, the functions exits immediately. Otherwise, the output is formatted like this:

    * \# specimen    experiment time    starting time    ending time
    * 1              208                120000           120208
    *

Note
  The unit of time is nanoseconds.

Referenced by eina_benchmark_run().