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_Counter * | eina_counter_new (const char *name) |
Return a counter. | |
EAPI void | eina_counter_free (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_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 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_new("malloc"); eina_counter_start(counter); test_malloc(); eina_counter_stop(counter, 1); eina_counter_dump(counter); eina_counter_free(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 sets up the error module of Eina and only on Windows, it initializes the high precision timer. It also registers, only on Windows, the error EINA_ERROR_COUNTER_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. See eina_error_init() for the documentation of the initialisation of the dependency modules.
Once the counter module is not used anymore, then eina_counter_shutdown() must be called to shut down the counter module.
- See also:
- eina_error_init()
- eina_init()
References eina_error_init(), eina_error_msg_register(), eina_error_set(), and eina_error_shutdown().
Referenced by eina_benchmark_init(), and eina_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 shuts down the counter module set up by eina_counter_init(). It is called by eina_shutdown(). It returns 0 when it is called the same number of times than eina_counter_init().
- See also:
- eina_error_shutdown()
- eina_shutdown()
References eina_error_shutdown().
Referenced by eina_benchmark_shutdown(), eina_init(), and eina_shutdown().
EAPI Eina_Counter * eina_counter_new | ( | 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.
Whe the new counter is not needed anymore, use eina_counter_free() to free the allocated memory.
References EINA_ERROR_OUT_OF_MEMORY, and eina_error_set().
Referenced by eina_benchmark_run().
EAPI void eina_counter_free | ( | 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 function returns immediatly.
References eina_inlist_remove().
Referenced by eina_benchmark_run().
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(), EINA_FALSE, and eina_inlist_prepend().
Referenced by eina_benchmark_run().
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.
References EINA_TRUE.
Referenced by eina_benchmark_run().
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.
References EINA_FALSE.
Referenced by eina_benchmark_run().