Counter
[Tools]

These functions allow you to get the time spent in a part of a code. More...


Typedefs

typedef struct _Eina_Counter Eina_Counter
 Counter type.

Functions

EAPI int eina_counter_init (void)
 Initialize the eina counter internal structure.
EAPI int eina_counter_shutdown (void)
 Shut down the eina counter internal structures.
EAPI Eina_Countereina_counter_add (const char *name)
 Return a counter.
EAPI void eina_counter_delete (Eina_Counter *counter)
 Delete a counter.
EAPI void eina_counter_start (Eina_Counter *counter)
 Start the time count.
EAPI void eina_counter_stop (Eina_Counter *counter, int specimen)
 Stop the time count.
EAPI char * eina_counter_dump (Eina_Counter *counter)
 Dump the result of all clocks of a counter to a stream.


Detailed Description

These functions allow you to get the time spent in a part of a code.

The counter system must be initialized with eina_counter_init() and shut down with eina_counter_shutdown(). The create a counter, use eina_counter_add(). To free it, use eina_counter_delete().

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 a number of that clock with the second argument of eina_counter_stop(). To send all the registered clocks to a stream (like stdout, ofr 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_counter_init())
    {
        printf("Error during the initialization of eina_counter module\n");
        return EXIT_FAILURE;
    }

    counter = eina_counter_add("malloc");

    eina_counter_start(counter);
    test_malloc();
    eina_counter_stop(counter, 1);

    eina_counter_dump(counter);

    eina_counter_delete(counter);
    eina_counter_shutdown();

    return EXIT_SUCCESS;
 }

Compile this code with the following commant:

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

The result should be something like that:

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

Note that the displayed time is in nanosecond.


Function Documentation

EAPI int eina_counter_init ( void   ) 

Initialize the eina counter internal structure.

Returns:
1 or greater on success, 0 on error.
This function allocates the memory needed by the counter, which means that it sets up the error module of Eina, and only on Windows it initializes the high precision timer. It also registers the errors EINA_ERROR_OUT_OF_MEMORY and, if on Windows, EINA_COUNTER_ERROR_WINDOWS. It is also called by eina_init(). It returns 0 on failure, otherwise it returns the number of times it has already been called.

References eina_error_init(), and eina_error_msg_register().

Referenced by eina_benchmark_init().

EAPI int eina_counter_shutdown ( void   ) 

Shut down the eina counter internal structures.

Returns:
0 when the counter module is completely shut down, 1 or greater otherwise.
This function just shuts down the error module. It is also called by eina_shutdown(). It returns 0 when it is called the same number of times than eina_counter_init().

References eina_error_shutdown().

Referenced by eina_benchmark_shutdown().

EAPI Eina_Counter * eina_counter_add ( const char *  name  ) 

Return a counter.

Parameters:
name The name of the counter.
This function returns a new counter. It is characterized by name. If name is NULL, the function returns NULL immediatly. If memory allocation fails, NULL is returned and the error is set to EINA_ERROR_OUT_OF_MEMORY.

References EINA_ERROR_OUT_OF_MEMORY, and eina_error_set().

EAPI void eina_counter_delete ( Eina_Counter counter  ) 

Delete a counter.

Parameters:
counter The counter to delete.
This function remove the clock of counter from the used clocks (see eina_counter_start()) and frees the memory allocated for counter. If counter is NULL, the functions returns immediatly.

EAPI void eina_counter_start ( Eina_Counter counter  ) 

Start the time count.

Parameters:
counter The counter.
This function specifies that the part of the code beginning just after its call is being to be timed, using counter. If counter is NULL, this function returns immediatly.

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 the error is set to EINA_ERROR_OUT_OF_MEMORY.

To stop the timing, eina_counter_stop() must be called with the same counter.

References EINA_ERROR_OUT_OF_MEMORY, eina_error_set(), and eina_inlist_prepend().

EAPI void eina_counter_stop ( Eina_Counter counter,
int  specimen 
)

Stop the time count.

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

EAPI char * eina_counter_dump ( Eina_Counter counter  ) 

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

Returns:
A string with a summary of the test.
Parameters:
counter The counter.
This function dump all the valid clocks of counter to the stream out. If counter or out are NULL, the functions exits immediatly. Otherwise, the output is formattted like that:

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

The unit of time is the nanosecond.