Commit | Line | Data |
---|---|---|
8c0b8894 PP |
1 | #ifndef BABELTRACE_GRAPH_CLOCK_CLASS_PRIORITY_MAP_H |
2 | #define BABELTRACE_GRAPH_CLOCK_CLASS_PRIORITY_MAP_H | |
3 | ||
4 | /* | |
5 | * Copyright 2017 Philippe Proulx <pproulx@efficios.com> | |
6 | * | |
7 | * Permission is hereby granted, free of charge, to any person obtaining a copy | |
8 | * of this software and associated documentation files (the "Software"), to deal | |
9 | * in the Software without restriction, including without limitation the rights | |
10 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | |
11 | * copies of the Software, and to permit persons to whom the Software is | |
12 | * furnished to do so, subject to the following conditions: | |
13 | * | |
14 | * The above copyright notice and this permission notice shall be included in | |
15 | * all copies or substantial portions of the Software. | |
16 | * | |
17 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
18 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
19 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | |
20 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | |
21 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
22 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | |
23 | * SOFTWARE. | |
24 | * | |
25 | * The Common Trace Format (CTF) Specification is available at | |
26 | * http://www.efficios.com/ctf | |
27 | */ | |
28 | ||
29 | #include <stdint.h> | |
30 | #include <stddef.h> | |
31 | #include <babeltrace/values.h> | |
32 | #include <babeltrace/ctf-ir/clock-class.h> | |
33 | ||
34 | #ifdef __cplusplus | |
35 | extern "C" { | |
36 | #endif | |
37 | ||
38 | /** | |
39 | @defgroup graphclockclassprioritymap Clock class priority map | |
40 | @ingroup graph | |
41 | @brief Clock class priority map. | |
42 | ||
43 | @code | |
44 | #include <babeltrace/graph/clock-class-priority-map.h> | |
45 | @endcode | |
46 | ||
47 | A <strong><em>clock class priority map</em></strong> object associates | |
48 | CTF IR clock classes to priorities. A clock class priority indicates | |
49 | which clock class you should choose to sort notifications by time. | |
50 | ||
51 | You need a clock class priority map object when you create | |
52 | an \link graphnotifevent event notification\endlink or | |
53 | an \link graphnotifinactivity inactivity notification\endlink. | |
54 | ||
55 | A priority is a 64-bit unsigned integer. A lower value has a | |
56 | \em higher priority. Multiple clock classes can have the same priority | |
57 | within a given clock class priority map. | |
58 | ||
fe650ea4 PP |
59 | The following functions can \em freeze clock class priority map objects: |
60 | ||
61 | - bt_notification_event_create() freezes its clock class priority | |
62 | map parameter. | |
63 | - bt_notification_inactivity_create() freezes its clock class priority | |
64 | map parameter. | |
65 | ||
66 | You cannot modify a frozen clock class priority map object: it is | |
67 | considered immutable, except for \link refs reference counting\endlink. | |
68 | ||
8c0b8894 PP |
69 | As with any Babeltrace object, clock class priority map objects have |
70 | <a href="https://en.wikipedia.org/wiki/Reference_counting">reference | |
71 | counts</a>. See \ref refs to learn more about the reference counting | |
72 | management of Babeltrace objects. | |
73 | ||
74 | @file | |
75 | @brief Clock class priority map type and functions. | |
76 | @sa graphclockclassprioritymap | |
77 | ||
78 | @addtogroup graphclockclassprioritymap | |
79 | @{ | |
80 | */ | |
81 | ||
82 | /** | |
83 | @struct bt_clock_class_priority_map | |
84 | @brief A clock class priority map. | |
85 | @sa graphclockclassprioritymap | |
86 | */ | |
87 | struct bt_clock_class_priority_map; | |
88 | ||
89 | /** | |
90 | @brief Creates an empty clock class priority map. | |
91 | ||
92 | @returns Created clock class priority map object, or \c NULL on error. | |
93 | ||
94 | @postsuccessrefcountret1 | |
95 | */ | |
96 | extern struct bt_clock_class_priority_map *bt_clock_class_priority_map_create(); | |
97 | ||
98 | /** | |
99 | @brief Returns the number of CTF IR clock classes contained in the | |
100 | clock class priority map \p clock_class_priority_map. | |
101 | ||
102 | @param[in] clock_class_priority_map Clock class priority map of | |
103 | which to get the number of | |
104 | clock classes. | |
105 | @returns Number of clock classes contained | |
106 | in \p clock_class_priority_map, | |
107 | or a negative value on error. | |
108 | ||
109 | @prenotnull{clock_class_priority_map} | |
110 | @postrefcountsame{clock_class_priority_map} | |
111 | */ | |
544d0515 | 112 | extern int64_t bt_clock_class_priority_map_get_clock_class_count( |
8c0b8894 PP |
113 | struct bt_clock_class_priority_map *clock_class_priority_map); |
114 | ||
115 | /** | |
116 | @brief Returns the CTF IR clock class at index \p index in the clock | |
117 | class priority map \p clock_class_priority_map. | |
118 | ||
119 | @param[in] clock_class_priority_map Clock class priority map of which | |
120 | to get the clock class at index | |
121 | \p index. | |
122 | @param[in] index Index of the clock class to find | |
123 | in \p clock_class_priority_map. | |
124 | @returns Clock class at index \p index in | |
125 | \p clock_class_priority_map, | |
126 | or \c NULL on error. | |
127 | ||
128 | @prenotnull{clock_class_priority_map} | |
129 | @pre \p index is lesser than the number of clock classes contained in | |
130 | the clock class priority map \p clock_class_priority_map (see | |
131 | bt_clock_class_priority_map_get_clock_class_count()). | |
132 | @postrefcountsame{clock_class_priority_map} | |
133 | ||
134 | @sa bt_clock_class_priority_map_get_clock_class_by_name(): Finds a clock | |
135 | class by name in a given clock class priority map. | |
136 | @sa bt_clock_class_priority_map_get_highest_priority_clock_class(): | |
137 | Returns the clock class with the highest priority contained | |
138 | in a given clock class priority map. | |
139 | @sa bt_clock_class_priority_map_add_clock_class(): Adds a clock class | |
140 | to a clock class priority map. | |
141 | */ | |
142 | extern struct bt_ctf_clock_class *bt_clock_class_priority_map_get_clock_class( | |
143 | struct bt_clock_class_priority_map *clock_class_priority_map, | |
144 | unsigned int index); | |
145 | ||
146 | /** | |
147 | @brief Returns the CTF IR clock class named \c name found in the clock | |
148 | class priority map \p clock_class_priority_map. | |
149 | ||
150 | @param[in] clock_class_priority_map Clock class priority map of | |
151 | which to get the clock class | |
152 | named \p name. | |
153 | @param[in] name Name of the clock class to find | |
154 | in \p clock_class_priority_map. | |
155 | @returns Clock class named \p name in | |
156 | \p clock_class_priority_map, | |
157 | or \c NULL on error. | |
158 | ||
159 | @prenotnull{clock_class_priority_map} | |
160 | @prenotnull{name} | |
161 | @postrefcountsame{clock_class_priority_map} | |
162 | @postsuccessrefcountretinc | |
163 | ||
164 | @sa bt_clock_class_priority_map_get_clock_class(): Returns the clock | |
165 | class contained in a given clock class priority map at | |
166 | a given index. | |
167 | @sa bt_clock_class_priority_map_get_highest_priority_clock_class(): | |
168 | Returns the clock class with the highest priority contained in | |
169 | a given clock class priority map. | |
170 | @sa bt_clock_class_priority_map_add_clock_class(): Adds a clock class | |
171 | to a clock class priority map. | |
172 | */ | |
173 | extern struct bt_ctf_clock_class * | |
174 | bt_clock_class_priority_map_get_clock_class_by_name( | |
175 | struct bt_clock_class_priority_map *clock_class_priority_map, | |
176 | const char *name); | |
177 | ||
178 | /** | |
179 | @brief Returns the CTF IR clock class with the currently highest | |
180 | priority within the clock class priority map | |
181 | \p clock_class_priority_map. | |
182 | ||
183 | If multiple clock classes share the same highest priority in | |
184 | \p clock_class_priority_map, you cannot deterministically know which one | |
185 | this function returns. | |
186 | ||
187 | @param[in] clock_class_priority_map Clock class priority map of which | |
188 | to get the clock class with the | |
189 | highest priority. | |
190 | @returns Clock class with the highest | |
191 | priority within | |
192 | \p clock_class_priority_map, or | |
193 | \c NULL on error or if there are | |
194 | no clock classes in | |
195 | \p clock_class_priority_map. | |
196 | ||
197 | @prenotnull{clock_class_priority_map} | |
198 | @postrefcountsame{clock_class_priority_map} | |
199 | @postsuccessrefcountretinc | |
200 | ||
201 | @sa bt_clock_class_priority_map_get_clock_class(): Returns the clock | |
202 | class contained in a given clock class priority map at | |
203 | a given index. | |
204 | @sa bt_clock_class_priority_map_get_clock_class_by_name(): Finds a | |
205 | clock class by name in a given clock class priority map. | |
206 | @sa bt_clock_class_priority_map_add_clock_class(): Adds a clock class | |
207 | to a clock class priority map. | |
208 | */ | |
209 | extern struct bt_ctf_clock_class * | |
210 | bt_clock_class_priority_map_get_highest_priority_clock_class( | |
211 | struct bt_clock_class_priority_map *clock_class_priority_map); | |
212 | ||
213 | /** | |
214 | @brief Returns the priority of the CTF IR clock class \p clock_class | |
215 | contained within the clock class priority map | |
216 | \p clock_class_priority_map. | |
217 | ||
218 | @param[in] clock_class_priority_map Clock class priority map | |
219 | containing \p clock_class. | |
220 | @param[in] clock_class Clock class of which to get the | |
221 | priority. | |
222 | @param[out] priority Returned priority of | |
223 | \p clock_class within | |
224 | \p clock_class_priority_map. | |
225 | @returns 0 on success, or a negative | |
226 | value on error. | |
227 | ||
228 | @prenotnull{clock_class_priority_map} | |
229 | @prenotnull{clock_class} | |
230 | @prenotnull{priority} | |
231 | @pre \p clock_class is contained in \p clock_class_priority_map (was | |
232 | previously added to \p clock_class_priority_map with | |
233 | bt_clock_class_priority_map_add_clock_class()). | |
234 | @postrefcountsame{clock_class_priority_map} | |
235 | @postrefcountsame{clock_class} | |
236 | ||
237 | @sa bt_clock_class_priority_map_get_highest_priority_clock_class(): | |
238 | Returns the clock class with the highest priority contained | |
239 | in a given clock class priority map. | |
240 | */ | |
241 | extern int bt_clock_class_priority_map_get_clock_class_priority( | |
242 | struct bt_clock_class_priority_map *clock_class_priority_map, | |
243 | struct bt_ctf_clock_class *clock_class, uint64_t *priority); | |
244 | ||
245 | /** | |
246 | @brief Adds the CTF IR clock class \p clock_class to the clock class | |
247 | priority map \p clock_class_priority_map with the | |
248 | priority \p priority. | |
249 | ||
250 | You can call this function even if \p clock_class is frozen. | |
251 | ||
252 | A lower priority value means a \em higher priority. Multiple clock | |
253 | classes can have the same priority within a given clock class priority | |
254 | map. | |
255 | ||
256 | @param[in] clock_class_priority_map Clock class priority map to | |
257 | which to add \p clock_class. | |
258 | @param[in] clock_class Clock class to add to | |
259 | \p clock_class_priority_map. | |
260 | @param[in] priority Priority of \p clock_class within | |
261 | \p clock_class_priority_map, | |
262 | where a lower value means a | |
263 | higher priority. | |
264 | @returns 0 on success, or a negative | |
265 | value on error. | |
266 | ||
267 | @prenotnull{clock_class_priority_map} | |
268 | @prenotnull{clock_class} | |
fe650ea4 | 269 | @prehot{clock_class_priority_map} |
8c0b8894 PP |
270 | @postrefcountsame{clock_class_priority_map} |
271 | @postsuccessrefcountinc{clock_class} | |
272 | ||
273 | @sa bt_clock_class_priority_map_get_clock_class(): Returns the clock | |
274 | class contained in a given clock class priority map | |
275 | at a given index. | |
276 | @sa bt_clock_class_priority_map_get_clock_class_by_name(): Finds a | |
277 | clock class by name in a given clock class priority map. | |
278 | */ | |
279 | extern int bt_clock_class_priority_map_add_clock_class( | |
280 | struct bt_clock_class_priority_map *clock_class_priority_map, | |
281 | struct bt_ctf_clock_class *clock_class, uint64_t priority); | |
282 | ||
7b5d7f76 PP |
283 | /** |
284 | @brief Creates a copy of the clock class priority map | |
285 | \p clock_class_priority_map. | |
286 | ||
287 | You can copy a frozen clock class priority map: the resulting copy is | |
288 | <em>not frozen</em>. | |
289 | ||
290 | @param[in] clock_class_priority_map Clock class priority map to copy. | |
291 | @returns Copy of \p clock_class_priority_map | |
292 | on success, or a negative value | |
293 | on error. | |
294 | ||
295 | @prenotnull{clock_class_priority_map} | |
296 | @postrefcountsame{clock_class_priority_map} | |
297 | @postsuccessrefcountret1 | |
298 | @post <strong>On success</strong>, the returned clock class priority map | |
299 | is not frozen. | |
300 | */ | |
301 | extern struct bt_clock_class_priority_map *bt_clock_class_priority_map_copy( | |
302 | struct bt_clock_class_priority_map *clock_class_priority_map); | |
303 | ||
8c0b8894 PP |
304 | /** @} */ |
305 | ||
306 | #ifdef __cplusplus | |
307 | } | |
308 | #endif | |
309 | ||
310 | #endif /* BABELTRACE_GRAPH_CLOCK_CLASS_PRIORITY_MAP_H */ |