2008-08-06 11:15:24 -07:00
|
|
|
/* EINA - EFL data type library
|
|
|
|
* Copyright (C) 2008 Cedric Bail
|
|
|
|
*
|
|
|
|
* This library is free software; you can redistribute it and/or
|
|
|
|
* modify it under the terms of the GNU Lesser General Public
|
|
|
|
* License as published by the Free Software Foundation; either
|
|
|
|
* version 2.1 of the License, or (at your option) any later version.
|
|
|
|
*
|
|
|
|
* This library is distributed in the hope that it will be useful,
|
|
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
|
|
* Lesser General Public License for more details.
|
|
|
|
*
|
|
|
|
* You should have received a copy of the GNU Lesser General Public
|
|
|
|
* License along with this library;
|
|
|
|
* if not, see <http://www.gnu.org/licenses/>.
|
|
|
|
*/
|
|
|
|
|
2008-09-17 11:55:54 -07:00
|
|
|
#ifndef EINA_COUNTER_H_
|
|
|
|
#define EINA_COUNTER_H_
|
2008-08-06 08:35:56 -07:00
|
|
|
|
|
|
|
#include "eina_types.h"
|
|
|
|
|
2011-04-07 04:40:55 -07:00
|
|
|
/**
|
2014-10-27 01:06:16 -07:00
|
|
|
* @defgroup Eina_Counter_Group Counter
|
|
|
|
* @ingroup Eina_Tools_Group
|
2011-04-07 04:40:55 -07:00
|
|
|
*
|
2014-10-27 01:06:16 -07:00
|
|
|
* @brief This group discusses the functions that allow you to get the time spent in a part of a code.
|
2011-04-07 04:40:55 -07:00
|
|
|
*
|
|
|
|
* Before using the counter system, Eina must be initialized with
|
2014-10-27 01:06:16 -07:00
|
|
|
* eina_init() and later shut down with eina_shutdown(). To create a
|
2011-04-07 04:40:55 -07:00
|
|
|
* 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,
|
2017-10-27 11:35:10 -07:00
|
|
|
* and eina_counter_stop() just after it. Each time you start timing
|
2014-10-27 01:06:16 -07:00
|
|
|
* a code, a clock is added to a list. You can give the number of that
|
2011-04-07 04:40:55 -07:00
|
|
|
* clock with the second argument of eina_counter_stop(). To send all
|
2014-10-27 01:06:16 -07:00
|
|
|
* the registered clocks to a stream (like stdout, for a file), use
|
2011-04-07 04:40:55 -07:00
|
|
|
* 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
|
|
|
|
*
|
2014-10-27 01:06:16 -07:00
|
|
|
* Compile this code with the following command:
|
2011-04-07 04:40:55 -07:00
|
|
|
*
|
|
|
|
* @verbatim
|
|
|
|
* gcc -Wall -o test_eina_counter test_eina.c `pkg-config --cflags --libs eina`
|
|
|
|
* @endverbatim
|
|
|
|
*
|
2014-10-27 01:06:16 -07:00
|
|
|
* The result should be something like this:
|
2011-04-07 04:40:55 -07:00
|
|
|
*
|
|
|
|
* @verbatim
|
|
|
|
* \# specimen experiment time starting time ending time
|
|
|
|
* 1 9794125 783816 10577941
|
|
|
|
* @endverbatim
|
|
|
|
*
|
2014-10-27 01:06:16 -07:00
|
|
|
* @note The displayed time is in nanoseconds.
|
2008-09-17 11:55:54 -07:00
|
|
|
*
|
|
|
|
* @{
|
|
|
|
*/
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @typedef Eina_Counter
|
2014-11-13 22:05:10 -08:00
|
|
|
* @brief An opaque type for counter.
|
2008-09-17 11:55:54 -07:00
|
|
|
*/
|
2008-08-06 08:35:56 -07:00
|
|
|
typedef struct _Eina_Counter Eina_Counter;
|
|
|
|
|
2011-04-07 04:40:55 -07:00
|
|
|
|
|
|
|
/**
|
2014-11-13 22:05:10 -08:00
|
|
|
* @brief Returns a counter.
|
|
|
|
* @details 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.
|
2011-04-07 04:40:55 -07:00
|
|
|
*
|
2017-02-19 22:18:21 -08:00
|
|
|
* @param[in] name The name of the counter
|
|
|
|
* @return A newly allocated counter
|
|
|
|
*
|
2017-10-27 11:35:10 -07:00
|
|
|
* @note When the new counter is not needed anymore, use eina_counter_free() to
|
2014-11-13 22:05:10 -08:00
|
|
|
* free the allocated memory.
|
2011-04-07 04:40:55 -07:00
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
EAPI Eina_Counter *eina_counter_new(const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
|
2011-04-07 04:40:55 -07:00
|
|
|
|
|
|
|
/**
|
2014-11-13 22:05:10 -08:00
|
|
|
* @brief Deletes a counter.
|
|
|
|
* @details This function removes 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.
|
2017-02-19 22:18:21 -08:00
|
|
|
* @param[in] counter The counter to delete
|
|
|
|
*
|
2011-04-07 04:40:55 -07:00
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
EAPI void eina_counter_free(Eina_Counter *counter) EINA_ARG_NONNULL(1);
|
2011-04-07 04:40:55 -07:00
|
|
|
|
|
|
|
/**
|
2014-11-13 22:05:10 -08:00
|
|
|
* @brief Starts the time count.
|
|
|
|
* @details This function specifies that the part of the code beginning just
|
|
|
|
* after its call is being timed, using @p counter. If
|
|
|
|
* @p counter is @c NULL, this function returns immediately.
|
2011-04-07 04:40:55 -07:00
|
|
|
*
|
2017-02-19 22:18:21 -08:00
|
|
|
* @param[in] counter The counter
|
|
|
|
*
|
2017-10-27 11:35:10 -07:00
|
|
|
* @note This function adds the clock associated with @p counter in a list. If
|
|
|
|
* the memory needed by that clock cannot be allocated, the function
|
2014-11-13 22:05:10 -08:00
|
|
|
* returns and nothing is done.
|
2011-04-07 04:40:55 -07:00
|
|
|
*
|
2014-11-13 22:05:10 -08:00
|
|
|
* @note To stop the timing, eina_counter_stop() must be called with the
|
|
|
|
* same counter.
|
2011-04-07 04:40:55 -07:00
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
EAPI void eina_counter_start(Eina_Counter *counter) EINA_ARG_NONNULL(1);
|
2011-04-07 04:40:55 -07:00
|
|
|
|
|
|
|
/**
|
2014-11-13 22:05:10 -08:00
|
|
|
* @brief Stops the time count.
|
|
|
|
* @details This function stops the timing that has been started with
|
|
|
|
* eina_counter_start(). @p counter must be the same as the one used
|
|
|
|
* with eina_counter_start(). @p specimen is the number of the
|
|
|
|
* test. If @p counter or its associated clock is @c NULL, or if the
|
|
|
|
* time can't be retrieved the function exits.
|
2017-02-19 22:18:21 -08:00
|
|
|
* @param[in] counter The counter
|
|
|
|
* @param[in] specimen The number of the test
|
|
|
|
*
|
2011-04-07 04:40:55 -07:00
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
EAPI void eina_counter_stop(Eina_Counter *counter,
|
|
|
|
int specimen) EINA_ARG_NONNULL(1);
|
2011-04-07 04:40:55 -07:00
|
|
|
|
|
|
|
/**
|
2014-11-13 22:05:10 -08:00
|
|
|
* @brief Dumps the result of all the clocks of a counter to a stream.
|
2018-07-12 00:27:15 -07:00
|
|
|
* @details This function returns a malloc'd string containing the dump of
|
2014-11-13 22:05:10 -08:00
|
|
|
* all the valid clocks of @p counter.
|
|
|
|
* If @p counter is @c NULL, the functions exits
|
|
|
|
* immediately. Otherwise, the output is formatted like this:
|
2011-04-07 04:40:55 -07:00
|
|
|
*
|
2017-02-19 22:18:21 -08:00
|
|
|
* @param[in] counter The counter
|
|
|
|
* @return A string with a summary of the test
|
|
|
|
*
|
2011-04-07 04:40:55 -07:00
|
|
|
* @verbatim
|
|
|
|
* \# specimen experiment time starting time ending time
|
|
|
|
* 1 208 120000 120208
|
|
|
|
* @endverbatim
|
|
|
|
*
|
2014-11-13 22:05:10 -08:00
|
|
|
* @note The unit of time is nanoseconds.
|
2011-04-07 04:40:55 -07:00
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
EAPI char *eina_counter_dump(Eina_Counter *counter) EINA_ARG_NONNULL(1);
|
2008-09-17 11:55:54 -07:00
|
|
|
|
|
|
|
/**
|
|
|
|
* @}
|
|
|
|
*/
|
2008-08-06 08:35:56 -07:00
|
|
|
|
2008-09-17 11:55:54 -07:00
|
|
|
#endif /* EINA_COUNTER_H_ */
|