1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
/* 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/>.
*/
#ifndef EINA_COUNTER_H_
#define EINA_COUNTER_H_
#include "eina_types.h"
/**
* @defgroup Eina_Counter_Group Counter
* @ingroup Eina_Tools_Group
*
* @brief This group discusses the functions that 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(). To create a
* counter, use eina_counter_new(). To free it, use
* eina_counter_free().
*
* To time a code sequence, call eina_counter_start() just before it,
* and eina_counter_stop() just after it. Each time you start timing
* a code, a clock is added to a list. You can give the number of that
* clock with the second argument of eina_counter_stop(). To send all
* the registered clocks to a stream (like stdout, for 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 command:
*
* @verbatim
* gcc -Wall -o test_eina_counter test_eina.c `pkg-config --cflags --libs eina`
* @endverbatim
*
* The result should be something like this:
*
* @verbatim
* \# specimen experiment time starting time ending time
* 1 9794125 783816 10577941
* @endverbatim
*
* @note The displayed time is in nanoseconds.
*
* @{
*/
/**
* @typedef Eina_Counter
* @brief An opaque type for counter.
*/
typedef struct _Eina_Counter Eina_Counter;
/**
* @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.
*
* @param[in] name The name of the counter
* @return A newly allocated counter
*
* @note When the new counter is not needed anymore, use eina_counter_free() to
* free the allocated memory.
*/
EINA_API Eina_Counter *eina_counter_new(const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @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.
* @param[in] counter The counter to delete
*
*/
EINA_API void eina_counter_free(Eina_Counter *counter) EINA_ARG_NONNULL(1);
/**
* @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.
*
* @param[in] counter The counter
*
* @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
* returns and nothing is done.
*
* @note To stop the timing, eina_counter_stop() must be called with the
* same counter.
*/
EINA_API void eina_counter_start(Eina_Counter *counter) EINA_ARG_NONNULL(1);
/**
* @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.
* @param[in] counter The counter
* @param[in] specimen The number of the test
*
*/
EINA_API void eina_counter_stop(Eina_Counter *counter,
int specimen) EINA_ARG_NONNULL(1);
/**
* @brief Dumps the result of all the clocks of a counter to a stream.
* @details This function returns a malloc'd string containing the dump of
* all the valid clocks of @p counter.
* If @p counter is @c NULL, the functions exits
* immediately. Otherwise, the output is formatted like this:
*
* @param[in] counter The counter
* @return A string with a summary of the test
*
* @verbatim
* \# specimen experiment time starting time ending time
* 1 208 120000 120208
* @endverbatim
*
* @note The unit of time is nanoseconds.
*/
EINA_API char *eina_counter_dump(Eina_Counter *counter) EINA_ARG_NONNULL(1);
/**
* @}
*/
#endif /* EINA_COUNTER_H_ */
|
