kimcinoo
/
efl
forked from enlightenment/efl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

more doxy -> .h 

SVN revision: 58421
This commit is contained in:
Carsten Haitzler 2011-04-07 11:40:55 +00:00
parent d44242d02c
commit a91e054426
2 changed files with 162 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

162
legacy/eina/src/include/eina_counter.h
View File

@ -21,6 +21,89 @@
#include "eina_types.h"
/**
* @addtogroup Eina_Counter_Group Counter
*
* @brief These functions 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(). 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:
*
* @code
* #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;
* }
* @endcode
*
* Compile this code with the following commant:
*
* @verbatim
* gcc -Wall -o test_eina_counter test_eina.c `pkg-config --cflags --libs eina`
* @endverbatim
*
* The result should be something like that:
*
* @verbatim
* \# specimen experiment time starting time ending time
* 1 9794125 783816 10577941
* @endverbatim
*
* Note that the displayed time is in nanosecond.
*
* @{
*/
/**
* @addtogroup Eina_Tools_Group Tools
*
@ -39,11 +122,86 @@
*/
typedef struct _Eina_Counter Eina_Counter;
/**
* @brief Return a counter.
*
* @param name The name of the counter.
* @return A newly allocated counter.
*
* This function returns a new counter. It is characterized by @p
* name. If @p name is @c NULL, the function returns @c NULL
* immediately. If memory allocation fails, @c 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.
*/
EAPI Eina_Counter *eina_counter_new(const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Delete a counter.
*
* @param counter The counter to delete.
*
* This function remove the clock of @p counter from the used clocks
* (see eina_counter_start()) and frees the memory allocated for
* @p counter. If @p counter is @c NULL, the function returns
* immediately.
*/
EAPI void eina_counter_free(Eina_Counter *counter) EINA_ARG_NONNULL(1);
/**
* @brief Start the time count.
*
* @param counter The counter.
*
* This function specifies that the part of the code beginning just
* after its call is being to be timed, using @p counter. If
* @p counter is @c NULL, this function returns immediately.
*
* This function adds the clock associated to @p 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.
*/
EAPI void eina_counter_start(Eina_Counter *counter) EINA_ARG_NONNULL(1);
/**
* @brief Stop the time count.
*
* @param counter The counter.
* @param specimen The number of the test.
*
* This function stop the timing that has been started with
* eina_counter_start(). @p counter must be the same than the one used
* with eina_counter_start(). @p specimen is the number of the
* test. If @p counter or its associated clock are @c NULL, or if the
* time can't be retrieved the function exits.
*/
EAPI void eina_counter_stop(Eina_Counter *counter,
int specimen) EINA_ARG_NONNULL(1);
/**
* @brief Dump the result of all clocks of a counter to a stream.
*
* @return A string with a summary of the test.
* @param counter The counter.
*
* This function returns an malloc'd string containing the dump of
* all the valid clocks of @p counter.
* If @p counter @c NULL, the functions exits
* immediately. Otherwise, the output is formattted like that:
*
* @verbatim
* \# specimen experiment time starting time ending time
* 1 208 120000 120208
* @endverbatim
*
* The unit of time is the nanosecond.
*/
EAPI char *eina_counter_dump(Eina_Counter *counter) EINA_ARG_NONNULL(1);
/**
@ -54,4 +212,8 @@ EAPI char *eina_counter_dump(Eina_Counter *counter) EINA_ARG_NONNULL(1);
* @}
*/
/**
* @}
*/
#endif /* EINA_COUNTER_H_ */

157
legacy/eina/src/lib/eina_counter.c
View File

@ -214,103 +214,6 @@ eina_counter_shutdown(void)
* API *
*============================================================================*/
/**
* @addtogroup Eina_Counter_Group Counter
*
* @brief These functions 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(). 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:
*
* @code
* #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;
* }
* @endcode
*
* Compile this code with the following commant:
*
* @verbatim
* gcc -Wall -o test_eina_counter test_eina.c `pkg-config --cflags --libs eina`
* @endverbatim
*
* The result should be something like that:
*
* @verbatim
* \# specimen experiment time starting time ending time
* 1 9794125 783816 10577941
* @endverbatim
*
* Note that the displayed time is in nanosecond.
*
* @{
*/
/**
* @brief Return a counter.
*
* @param name The name of the counter.
* @return A newly allocated counter.
*
* This function returns a new counter. It is characterized by @p
* name. If @p name is @c NULL, the function returns @c NULL
* immediately. If memory allocation fails, @c 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.
*/
EAPI Eina_Counter *
eina_counter_new(const char *name)
{
@ -335,16 +238,6 @@ eina_counter_new(const char *name)
return counter;
}
/**
* @brief Delete a counter.
*
* @param counter The counter to delete.
*
* This function remove the clock of @p counter from the used clocks
* (see eina_counter_start()) and frees the memory allocated for
* @p counter. If @p counter is @c NULL, the function returns
* immediately.
*/
EAPI void
eina_counter_free(Eina_Counter *counter)
{
@ -361,22 +254,6 @@ eina_counter_free(Eina_Counter *counter)
free(counter);
}
/**
* @brief Start the time count.
*
* @param counter The counter.
*
* This function specifies that the part of the code beginning just
* after its call is being to be timed, using @p counter. If
* @p counter is @c NULL, this function returns immediately.
*
* This function adds the clock associated to @p 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.
*/
EAPI void
eina_counter_start(Eina_Counter *counter)
{
@ -401,18 +278,6 @@ eina_counter_start(Eina_Counter *counter)
clk->start = tp;
}
/**
* @brief Stop the time count.
*
* @param counter The counter.
* @param specimen The number of the test.
*
* This function stop the timing that has been started with
* eina_counter_start(). @p counter must be the same than the one used
* with eina_counter_start(). @p specimen is the number of the
* test. If @p counter or its associated clock are @c NULL, or if the
* time can't be retrieved the function exits.
*/
EAPI void
eina_counter_stop(Eina_Counter *counter, int specimen)
{
@ -433,24 +298,6 @@ eina_counter_stop(Eina_Counter *counter, int specimen)
clk->valid = EINA_TRUE;
}
/**
* @brief Dump the result of all clocks of a counter to a stream.
*
* @return A string with a summary of the test.
* @param counter The counter.
*
* This function returns an malloc'd string containing the dump of
* all the valid clocks of @p counter.
* If @p counter @c NULL, the functions exits
* immediately. Otherwise, the output is formattted like that:
*
* @verbatim
* \# specimen experiment time starting time ending time
* 1 208 120000 120208
* @endverbatim
*
* The unit of time is the nanosecond.
*/
EAPI char *
eina_counter_dump(Eina_Counter *counter)
{
@ -509,7 +356,3 @@ eina_counter_dump(Eina_Counter *counter)
return result;
}
/**
* @}
*/