src/include/eina_counter.h

   1 /* EINA - EFL data type library
   2  * Copyright (C) 2008 Cedric Bail
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2.1 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library;
  16  * if not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef EINA_COUNTER_H_
  20 #define EINA_COUNTER_H_
  21
  22 #include "eina_types.h"
  23
  24 /**
  25  * @addtogroup Eina_Counter_Group Counter
  26  *
  27  * @brief These functions allow you to get the time spent in a part of a code.
  28  *
  29  * Before using the counter system, Eina must be initialized with
  30  * eina_init() and later shut down with eina_shutdown(). The create a
  31  * counter, use eina_counter_new(). To free it, use
  32  * eina_counter_free().
  33  *
  34  * To time a part of a code, call eina_counter_start() just before it,
  35  * and eina_counter_stop() just after it. Each time you start to time
  36  * a code, a clock is added to a list. You can give a number of that
  37  * clock with the second argument of eina_counter_stop(). To send all
  38  * the registered clocks to a stream (like stdout, ofr a file), use
  39  * eina_counter_dump().
  40  *
  41  * Here is a straightforward example:
  42  *
  43  * @code
  44  * #include <stdlib.h>
  45  * #include <stdio.h>
  46  *
  47  * #include <eina_counter.h>
  48  *
  49  * void test_malloc(void)
  50  * {
  51  *    int i;
  52  *
  53  *    for (i = 0; i < 100000; ++i)
  54  *    {
  55  *       void *buf;
  56  *
  57  *       buf = malloc(100);
  58  *       free(buf);
  59  *    }
  60  * }
  61  *
  62  * int main(void)
  63  * {
  64  *    Eina_Counter *counter;
  65  *
  66  *    if (!eina_init())
  67  *    {
  68  *        printf("Error during the initialization of eina\n");
  69  *        return EXIT_FAILURE;
  70  *    }
  71  *
  72  *    counter = eina_counter_new("malloc");
  73  *
  74  *    eina_counter_start(counter);
  75  *    test_malloc();
  76  *    eina_counter_stop(counter, 1);
  77  *
  78  *    char* result = eina_counter_dump(counter);
  79  *    printf("%s", result);
  80  *    free(result);
  81  *
  82  *    eina_counter_free(counter);
  83  *    eina_shutdown();
  84  *
  85  *    return EXIT_SUCCESS;
  86  * }
  87  * @endcode
  88  *
  89  * Compile this code with the following commant:
  90  *
  91  * @verbatim
  92  * gcc -Wall -o test_eina_counter test_eina.c `pkg-config --cflags --libs eina`
  93  * @endverbatim
  94  *
  95  * The result should be something like that:
  96  *
  97  * @verbatim
  98  * \# specimen    experiment time    starting time    ending time
  99  * 1              9794125            783816           10577941
 100  * @endverbatim
 101  *
 102  * @note The displayed time is in nanosecond.
 103  */
 104
 105 /**
 106  * @addtogroup Eina_Tools_Group Tools
 107  *
 108  * @{
 109  */
 110
 111 /**
 112  * @defgroup Eina_Counter_Group Counter
 113  *
 114  * @{
 115  */
 116
 117 /**
 118  * @typedef Eina_Counter
 119  * Counter type.
 120  */
 121 typedef struct _Eina_Counter Eina_Counter;
 122
 123
 124 /**
 125  * @brief Return a counter.
 126  *
 127  * @param name The name of the counter.
 128  * @return A newly allocated counter.
 129  *
 130  * This function returns a new counter. It is characterized by @p
 131  * name. If @p name is @c NULL, the function returns @c NULL
 132  * immediately. If memory allocation fails, @c NULL is returned and the
 133  * error is set to #EINA_ERROR_OUT_OF_MEMORY.
 134  *
 135  * Whe the new counter is not needed anymore, use eina_counter_free() to
 136  * free the allocated memory.
 137  */
 138 EAPI Eina_Counter *eina_counter_new(const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
 139
 140 /**
 141  * @brief Delete a counter.
 142  *
 143  * @param counter The counter to delete.
 144  *
 145  * This function remove the clock of @p counter from the used clocks
 146  * (see eina_counter_start()) and frees the memory allocated for
 147  * @p counter. If @p counter is @c NULL, the function returns
 148  * immediately.
 149  */
 150 EAPI void          eina_counter_free(Eina_Counter *counter) EINA_ARG_NONNULL(1);
 151
 152 /**
 153  * @brief Start the time count.
 154  *
 155  * @param counter The counter.
 156  *
 157  * This function specifies that the part of the code beginning just
 158  * after its call is being to be timed, using @p counter. If
 159  * @p counter is @c NULL, this function returns immediately.
 160  *
 161  * This function adds the clock associated to @p counter in a list. If
 162  * the memory needed by that clock can not be allocated, the function
 163  * returns and the error is set to #EINA_ERROR_OUT_OF_MEMORY.
 164  *
 165  * To stop the timing, eina_counter_stop() must be called with the
 166  * same counter.
 167  */
 168 EAPI void          eina_counter_start(Eina_Counter *counter) EINA_ARG_NONNULL(1);
 169
 170 /**
 171  * @brief Stop the time count.
 172  *
 173  * @param counter The counter.
 174  * @param specimen The number of the test.
 175  *
 176  * This function stop the timing that has been started with
 177  * eina_counter_start(). @p counter must be the same than the one used
 178  * with eina_counter_start(). @p specimen is the number of the
 179  * test. If @p counter or its associated clock are  @c NULL, or if the
 180  * time can't be retrieved the function exits.
 181  */
 182 EAPI void          eina_counter_stop(Eina_Counter *counter,
 183                                      int           specimen) EINA_ARG_NONNULL(1);
 184
 185 /**
 186  * @brief Dump the result of all clocks of a counter to a stream.
 187  *
 188  * @return A string with a summary of the test.
 189  * @param counter The counter.
 190  *
 191  * This function returns an malloc'd string containing the dump of
 192  * all the valid clocks of @p counter.
 193  * If @p counter @c NULL, the functions exits
 194  * immediately. Otherwise, the output is formattted like that:
 195  *
 196  * @verbatim
 197  * \# specimen    experiment time    starting time    ending time
 198  * 1              208                120000           120208
 199  * @endverbatim
 200  *
 201  * The unit of time is the nanosecond.
 202  */
 203 EAPI char         *eina_counter_dump(Eina_Counter *counter) EINA_ARG_NONNULL(1);
 204
 205 /**
 206  * @}
 207  */
 208
 209 /**
 210  * @}
 211  */
 212
 213 #endif /* EINA_COUNTER_H_ */