diff options
author | David Walter Seikel | 2012-01-04 18:41:13 +1000 |
---|---|---|
committer | David Walter Seikel | 2012-01-04 18:41:13 +1000 |
commit | dd7595a3475407a7fa96a97393bae8c5220e8762 (patch) | |
tree | e341e911d7eb911a51684a7412ef7f7c7605d28e /libraries/eina/src/include/eina_counter.h | |
parent | Add the skeleton. (diff) | |
download | SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.zip SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.gz SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.bz2 SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.xz |
Add the base Enlightenment Foundation Libraries - eina, eet, evas, ecore, embryo, and edje.
Note that embryo wont be used, but I'm not sure yet if you can build edje without it.
Diffstat (limited to 'libraries/eina/src/include/eina_counter.h')
-rw-r--r-- | libraries/eina/src/include/eina_counter.h | 213 |
1 files changed, 213 insertions, 0 deletions
diff --git a/libraries/eina/src/include/eina_counter.h b/libraries/eina/src/include/eina_counter.h new file mode 100644 index 0000000..26bee06 --- /dev/null +++ b/libraries/eina/src/include/eina_counter.h | |||
@@ -0,0 +1,213 @@ | |||
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 that 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_ */ | ||