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 | ||
094ff7c0 PP |
29 | /* For bt_get() */ |
30 | #include <babeltrace/ref.h> | |
31 | ||
8c0b8894 PP |
32 | #include <stdint.h> |
33 | #include <stddef.h> | |
8c0b8894 PP |
34 | |
35 | #ifdef __cplusplus | |
36 | extern "C" { | |
37 | #endif | |
38 | ||
50842bdc | 39 | struct bt_clock_class; |
9d408fca | 40 | |
8c0b8894 PP |
41 | /** |
42 | @defgroup graphclockclassprioritymap Clock class priority map | |
43 | @ingroup graph | |
44 | @brief Clock class priority map. | |
45 | ||
46 | @code | |
47 | #include <babeltrace/graph/clock-class-priority-map.h> | |
48 | @endcode | |
49 | ||
50 | A <strong><em>clock class priority map</em></strong> object associates | |
51 | CTF IR clock classes to priorities. A clock class priority indicates | |
52 | which clock class you should choose to sort notifications by time. | |
53 | ||
54 | You need a clock class priority map object when you create | |
55 | an \link graphnotifevent event notification\endlink or | |
56 | an \link graphnotifinactivity inactivity notification\endlink. | |
57 | ||
58 | A priority is a 64-bit unsigned integer. A lower value has a | |
59 | \em higher priority. Multiple clock classes can have the same priority | |
60 | within a given clock class priority map. | |
61 | ||
fe650ea4 PP |
62 | The following functions can \em freeze clock class priority map objects: |
63 | ||
64 | - bt_notification_event_create() freezes its clock class priority | |
65 | map parameter. | |
66 | - bt_notification_inactivity_create() freezes its clock class priority | |
67 | map parameter. | |
68 | ||
69 | You cannot modify a frozen clock class priority map object: it is | |
70 | considered immutable, except for \link refs reference counting\endlink. | |
71 | ||
8c0b8894 PP |
72 | As with any Babeltrace object, clock class priority map objects have |
73 | <a href="https://en.wikipedia.org/wiki/Reference_counting">reference | |
74 | counts</a>. See \ref refs to learn more about the reference counting | |
75 | management of Babeltrace objects. | |
76 | ||
77 | @file | |
78 | @brief Clock class priority map type and functions. | |
79 | @sa graphclockclassprioritymap | |
80 | ||
81 | @addtogroup graphclockclassprioritymap | |
82 | @{ | |
83 | */ | |
84 | ||
85 | /** | |
86 | @struct bt_clock_class_priority_map | |
87 | @brief A clock class priority map. | |
88 | @sa graphclockclassprioritymap | |
89 | */ | |
90 | struct bt_clock_class_priority_map; | |
91 | ||
92 | /** | |
93 | @brief Creates an empty clock class priority map. | |
94 | ||
95 | @returns Created clock class priority map object, or \c NULL on error. | |
96 | ||
97 | @postsuccessrefcountret1 | |
98 | */ | |
375d5f6a | 99 | extern struct bt_clock_class_priority_map *bt_clock_class_priority_map_create(void); |
8c0b8894 PP |
100 | |
101 | /** | |
102 | @brief Returns the number of CTF IR clock classes contained in the | |
103 | clock class priority map \p clock_class_priority_map. | |
104 | ||
105 | @param[in] clock_class_priority_map Clock class priority map of | |
106 | which to get the number of | |
107 | clock classes. | |
108 | @returns Number of clock classes contained | |
109 | in \p clock_class_priority_map, | |
110 | or a negative value on error. | |
111 | ||
112 | @prenotnull{clock_class_priority_map} | |
113 | @postrefcountsame{clock_class_priority_map} | |
114 | */ | |
544d0515 | 115 | extern int64_t bt_clock_class_priority_map_get_clock_class_count( |
8c0b8894 PP |
116 | struct bt_clock_class_priority_map *clock_class_priority_map); |
117 | ||
094ff7c0 PP |
118 | extern struct bt_clock_class * |
119 | bt_clock_class_priority_map_borrow_clock_class_by_index( | |
120 | struct bt_clock_class_priority_map *clock_class_priority_map, | |
121 | uint64_t index); | |
122 | ||
8c0b8894 PP |
123 | /** |
124 | @brief Returns the CTF IR clock class at index \p index in the clock | |
125 | class priority map \p clock_class_priority_map. | |
126 | ||
127 | @param[in] clock_class_priority_map Clock class priority map of which | |
128 | to get the clock class at index | |
129 | \p index. | |
130 | @param[in] index Index of the clock class to find | |
131 | in \p clock_class_priority_map. | |
132 | @returns Clock class at index \p index in | |
133 | \p clock_class_priority_map, | |
134 | or \c NULL on error. | |
135 | ||
136 | @prenotnull{clock_class_priority_map} | |
137 | @pre \p index is lesser than the number of clock classes contained in | |
138 | the clock class priority map \p clock_class_priority_map (see | |
139 | bt_clock_class_priority_map_get_clock_class_count()). | |
140 | @postrefcountsame{clock_class_priority_map} | |
141 | ||
142 | @sa bt_clock_class_priority_map_get_clock_class_by_name(): Finds a clock | |
143 | class by name in a given clock class priority map. | |
144 | @sa bt_clock_class_priority_map_get_highest_priority_clock_class(): | |
145 | Returns the clock class with the highest priority contained | |
146 | in a given clock class priority map. | |
147 | @sa bt_clock_class_priority_map_add_clock_class(): Adds a clock class | |
148 | to a clock class priority map. | |
149 | */ | |
094ff7c0 PP |
150 | static inline |
151 | struct bt_clock_class * | |
9ac68eb1 | 152 | bt_clock_class_priority_map_get_clock_class_by_index( |
8c0b8894 | 153 | struct bt_clock_class_priority_map *clock_class_priority_map, |
094ff7c0 PP |
154 | uint64_t index) |
155 | { | |
156 | return bt_get(bt_clock_class_priority_map_borrow_clock_class_by_index( | |
157 | clock_class_priority_map, index)); | |
158 | } | |
159 | ||
160 | extern struct bt_clock_class * | |
161 | bt_clock_class_priority_map_borrow_clock_class_by_name( | |
162 | struct bt_clock_class_priority_map *clock_class_priority_map, | |
163 | const char *name); | |
8c0b8894 PP |
164 | |
165 | /** | |
166 | @brief Returns the CTF IR clock class named \c name found in the clock | |
167 | class priority map \p clock_class_priority_map. | |
168 | ||
169 | @param[in] clock_class_priority_map Clock class priority map of | |
170 | which to get the clock class | |
171 | named \p name. | |
172 | @param[in] name Name of the clock class to find | |
173 | in \p clock_class_priority_map. | |
174 | @returns Clock class named \p name in | |
175 | \p clock_class_priority_map, | |
176 | or \c NULL on error. | |
177 | ||
178 | @prenotnull{clock_class_priority_map} | |
179 | @prenotnull{name} | |
180 | @postrefcountsame{clock_class_priority_map} | |
181 | @postsuccessrefcountretinc | |
182 | ||
9ac68eb1 | 183 | @sa bt_clock_class_priority_map_get_clock_class_by_index(): Returns the clock |
8c0b8894 PP |
184 | class contained in a given clock class priority map at |
185 | a given index. | |
186 | @sa bt_clock_class_priority_map_get_highest_priority_clock_class(): | |
187 | Returns the clock class with the highest priority contained in | |
188 | a given clock class priority map. | |
189 | @sa bt_clock_class_priority_map_add_clock_class(): Adds a clock class | |
190 | to a clock class priority map. | |
191 | */ | |
094ff7c0 PP |
192 | static inline |
193 | struct bt_clock_class *bt_clock_class_priority_map_get_clock_class_by_name( | |
8c0b8894 | 194 | struct bt_clock_class_priority_map *clock_class_priority_map, |
094ff7c0 PP |
195 | const char *name) |
196 | { | |
197 | return bt_get(bt_clock_class_priority_map_borrow_clock_class_by_name( | |
198 | clock_class_priority_map, name)); | |
199 | } | |
200 | ||
201 | extern struct bt_clock_class * | |
202 | bt_clock_class_priority_map_borrow_highest_priority_clock_class( | |
203 | struct bt_clock_class_priority_map *clock_class_priority_map); | |
8c0b8894 PP |
204 | |
205 | /** | |
206 | @brief Returns the CTF IR clock class with the currently highest | |
207 | priority within the clock class priority map | |
208 | \p clock_class_priority_map. | |
209 | ||
210 | If multiple clock classes share the same highest priority in | |
211 | \p clock_class_priority_map, you cannot deterministically know which one | |
212 | this function returns. | |
213 | ||
214 | @param[in] clock_class_priority_map Clock class priority map of which | |
215 | to get the clock class with the | |
216 | highest priority. | |
217 | @returns Clock class with the highest | |
218 | priority within | |
219 | \p clock_class_priority_map, or | |
220 | \c NULL on error or if there are | |
221 | no clock classes in | |
222 | \p clock_class_priority_map. | |
223 | ||
224 | @prenotnull{clock_class_priority_map} | |
225 | @postrefcountsame{clock_class_priority_map} | |
226 | @postsuccessrefcountretinc | |
227 | ||
9ac68eb1 | 228 | @sa bt_clock_class_priority_map_get_clock_class_by_index(): Returns the clock |
8c0b8894 PP |
229 | class contained in a given clock class priority map at |
230 | a given index. | |
231 | @sa bt_clock_class_priority_map_get_clock_class_by_name(): Finds a | |
232 | clock class by name in a given clock class priority map. | |
233 | @sa bt_clock_class_priority_map_add_clock_class(): Adds a clock class | |
234 | to a clock class priority map. | |
235 | */ | |
094ff7c0 PP |
236 | static inline |
237 | struct bt_clock_class * | |
8c0b8894 | 238 | bt_clock_class_priority_map_get_highest_priority_clock_class( |
094ff7c0 PP |
239 | struct bt_clock_class_priority_map *clock_class_priority_map) |
240 | { | |
241 | return bt_get( | |
242 | bt_clock_class_priority_map_borrow_highest_priority_clock_class( | |
243 | clock_class_priority_map)); | |
244 | } | |
8c0b8894 PP |
245 | |
246 | /** | |
247 | @brief Returns the priority of the CTF IR clock class \p clock_class | |
248 | contained within the clock class priority map | |
249 | \p clock_class_priority_map. | |
250 | ||
251 | @param[in] clock_class_priority_map Clock class priority map | |
252 | containing \p clock_class. | |
253 | @param[in] clock_class Clock class of which to get the | |
254 | priority. | |
255 | @param[out] priority Returned priority of | |
256 | \p clock_class within | |
257 | \p clock_class_priority_map. | |
258 | @returns 0 on success, or a negative | |
259 | value on error. | |
260 | ||
261 | @prenotnull{clock_class_priority_map} | |
262 | @prenotnull{clock_class} | |
263 | @prenotnull{priority} | |
264 | @pre \p clock_class is contained in \p clock_class_priority_map (was | |
265 | previously added to \p clock_class_priority_map with | |
266 | bt_clock_class_priority_map_add_clock_class()). | |
267 | @postrefcountsame{clock_class_priority_map} | |
268 | @postrefcountsame{clock_class} | |
269 | ||
270 | @sa bt_clock_class_priority_map_get_highest_priority_clock_class(): | |
271 | Returns the clock class with the highest priority contained | |
272 | in a given clock class priority map. | |
273 | */ | |
274 | extern int bt_clock_class_priority_map_get_clock_class_priority( | |
275 | struct bt_clock_class_priority_map *clock_class_priority_map, | |
50842bdc | 276 | struct bt_clock_class *clock_class, uint64_t *priority); |
8c0b8894 PP |
277 | |
278 | /** | |
279 | @brief Adds the CTF IR clock class \p clock_class to the clock class | |
280 | priority map \p clock_class_priority_map with the | |
281 | priority \p priority. | |
282 | ||
283 | You can call this function even if \p clock_class is frozen. | |
284 | ||
285 | A lower priority value means a \em higher priority. Multiple clock | |
286 | classes can have the same priority within a given clock class priority | |
287 | map. | |
288 | ||
289 | @param[in] clock_class_priority_map Clock class priority map to | |
290 | which to add \p clock_class. | |
291 | @param[in] clock_class Clock class to add to | |
292 | \p clock_class_priority_map. | |
293 | @param[in] priority Priority of \p clock_class within | |
294 | \p clock_class_priority_map, | |
295 | where a lower value means a | |
296 | higher priority. | |
297 | @returns 0 on success, or a negative | |
298 | value on error. | |
299 | ||
300 | @prenotnull{clock_class_priority_map} | |
301 | @prenotnull{clock_class} | |
fe650ea4 | 302 | @prehot{clock_class_priority_map} |
8c0b8894 PP |
303 | @postrefcountsame{clock_class_priority_map} |
304 | @postsuccessrefcountinc{clock_class} | |
305 | ||
9ac68eb1 | 306 | @sa bt_clock_class_priority_map_get_clock_class_by_index(): Returns the clock |
8c0b8894 PP |
307 | class contained in a given clock class priority map |
308 | at a given index. | |
309 | @sa bt_clock_class_priority_map_get_clock_class_by_name(): Finds a | |
310 | clock class by name in a given clock class priority map. | |
311 | */ | |
312 | extern int bt_clock_class_priority_map_add_clock_class( | |
313 | struct bt_clock_class_priority_map *clock_class_priority_map, | |
50842bdc | 314 | struct bt_clock_class *clock_class, uint64_t priority); |
8c0b8894 | 315 | |
7b5d7f76 PP |
316 | /** |
317 | @brief Creates a copy of the clock class priority map | |
318 | \p clock_class_priority_map. | |
319 | ||
320 | You can copy a frozen clock class priority map: the resulting copy is | |
321 | <em>not frozen</em>. | |
322 | ||
323 | @param[in] clock_class_priority_map Clock class priority map to copy. | |
324 | @returns Copy of \p clock_class_priority_map | |
325 | on success, or a negative value | |
326 | on error. | |
327 | ||
328 | @prenotnull{clock_class_priority_map} | |
329 | @postrefcountsame{clock_class_priority_map} | |
330 | @postsuccessrefcountret1 | |
331 | @post <strong>On success</strong>, the returned clock class priority map | |
332 | is not frozen. | |
333 | */ | |
334 | extern struct bt_clock_class_priority_map *bt_clock_class_priority_map_copy( | |
335 | struct bt_clock_class_priority_map *clock_class_priority_map); | |
336 | ||
8c0b8894 PP |
337 | /** @} */ |
338 | ||
339 | #ifdef __cplusplus | |
340 | } | |
341 | #endif | |
342 | ||
343 | #endif /* BABELTRACE_GRAPH_CLOCK_CLASS_PRIORITY_MAP_H */ |