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

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

## 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 code sequence, call eina_counter_start() just before it, and eina_counter_stop() just after it. Each time you start timing 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;
}
eina_counter_dump
EINA_API char * eina_counter_dump(Eina_Counter *counter)
Dumps the result of all the clocks of a counter to a stream.
Definition eina_counter.c:189
eina_counter_start
EINA_API void eina_counter_start(Eina_Counter *counter)
Starts the time count.
Definition eina_counter.c:151
eina_counter_new
EINA_API Eina_Counter * eina_counter_new(const char *name)
Returns a counter.
Definition eina_counter.c:117
eina_counter_stop
EINA_API void eina_counter_stop(Eina_Counter *counter, int specimen)
Stops the time count.
Definition eina_counter.c:169
eina_counter_free
EINA_API void eina_counter_free(Eina_Counter *counter)
Deletes a counter.
Definition eina_counter.c:135
Eina_Counter
struct _Eina_Counter Eina_Counter
An opaque type for counter.
Definition eina_counter.h:112
eina_shutdown
EINA_API int eina_shutdown(void)
Shuts down the Eina library.
Definition eina_main.c:379
eina_init
EINA_API int eina_init(void)
Initializes the Eina library.
Definition eina_main.c:291

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()

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

Returns a 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.

Parameters

  [in] | name | The name of the counter

Returns
  A newly allocated counter

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

References EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by eina_benchmark_run().

## eina_counter_free()

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

Deletes a counter.

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.

Parameters

  [in] | counter | The counter to delete

References eina_inlist_remove(), and EINA_SAFETY_ON_NULL_RETURN.

Referenced by eina_benchmark_run().

## eina_counter_start()

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

Starts the time count.

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.

Parameters

  [in] | counter | The counter

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

References EINA_FALSE, EINA_INLIST_GET, eina_inlist_prepend(), and EINA_SAFETY_ON_NULL_RETURN.

Referenced by eina_benchmark_run().

## eina_counter_stop()

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

Stops the time count.

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.

Parameters

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

References EINA_SAFETY_ON_NULL_RETURN, and EINA_TRUE.

Referenced by eina_benchmark_run().

## eina_counter_dump()

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

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

This function returns a 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:

Parameters

  [in] | counter | The counter

Returns
  A string with a summary of the test

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

Note
  The unit of time is nanoseconds.

References EINA_FALSE, EINA_INLIST_REVERSE_FOREACH, and EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by eina_benchmark_run().