1 #ifndef BABELTRACE_GRAPH_CLOCK_CLASS_PRIORITY_MAP_H
2 #define BABELTRACE_GRAPH_CLOCK_CLASS_PRIORITY_MAP_H
5 * Copyright 2017 Philippe Proulx <pproulx@efficios.com>
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:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
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
25 * The Common Trace Format (CTF) Specification is available at
26 * http://www.efficios.com/ctf
30 #include <babeltrace/ref.h>
39 struct bt_clock_class
;
42 @defgroup graphclockclassprioritymap Clock class priority map
44 @brief Clock class priority map.
47 #include <babeltrace/graph/clock-class-priority-map.h>
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.
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.
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.
62 The following functions can \em freeze clock class priority map objects:
64 - bt_notification_event_create() freezes its clock class priority
66 - bt_notification_inactivity_create() freezes its clock class priority
69 You cannot modify a frozen clock class priority map object: it is
70 considered immutable, except for \link refs reference counting\endlink.
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.
78 @brief Clock class priority map type and functions.
79 @sa graphclockclassprioritymap
81 @addtogroup graphclockclassprioritymap
86 @struct bt_clock_class_priority_map
87 @brief A clock class priority map.
88 @sa graphclockclassprioritymap
90 struct bt_clock_class_priority_map
;
93 @brief Creates an empty clock class priority map.
95 @returns Created clock class priority map object, or \c NULL on error.
97 @postsuccessrefcountret1
99 extern struct bt_clock_class_priority_map
*bt_clock_class_priority_map_create(void);
102 @brief Returns the number of CTF IR clock classes contained in the
103 clock class priority map \p clock_class_priority_map.
105 @param[in] clock_class_priority_map Clock class priority map of
106 which to get the number of
108 @returns Number of clock classes contained
109 in \p clock_class_priority_map,
110 or a negative value on error.
112 @prenotnull{clock_class_priority_map}
113 @postrefcountsame{clock_class_priority_map}
115 extern int64_t bt_clock_class_priority_map_get_clock_class_count(
116 struct bt_clock_class_priority_map
*clock_class_priority_map
);
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
,
124 @brief Returns the CTF IR clock class at index \p index in the clock
125 class priority map \p clock_class_priority_map.
127 @param[in] clock_class_priority_map Clock class priority map of which
128 to get the clock class at 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,
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}
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.
151 struct bt_clock_class
*
152 bt_clock_class_priority_map_get_clock_class_by_index(
153 struct bt_clock_class_priority_map
*clock_class_priority_map
,
156 return bt_get(bt_clock_class_priority_map_borrow_clock_class_by_index(
157 clock_class_priority_map
, index
));
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
,
166 @brief Returns the CTF IR clock class named \c name found in the clock
167 class priority map \p clock_class_priority_map.
169 @param[in] clock_class_priority_map Clock class priority map of
170 which to get the clock class
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,
178 @prenotnull{clock_class_priority_map}
180 @postrefcountsame{clock_class_priority_map}
181 @postsuccessrefcountretinc
183 @sa bt_clock_class_priority_map_get_clock_class_by_index(): Returns the clock
184 class contained in a given clock class priority map at
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.
193 struct bt_clock_class
*bt_clock_class_priority_map_get_clock_class_by_name(
194 struct bt_clock_class_priority_map
*clock_class_priority_map
,
197 return bt_get(bt_clock_class_priority_map_borrow_clock_class_by_name(
198 clock_class_priority_map
, name
));
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
);
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.
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.
214 @param[in] clock_class_priority_map Clock class priority map of which
215 to get the clock class with the
217 @returns Clock class with the highest
219 \p clock_class_priority_map, or
220 \c NULL on error or if there are
222 \p clock_class_priority_map.
224 @prenotnull{clock_class_priority_map}
225 @postrefcountsame{clock_class_priority_map}
226 @postsuccessrefcountretinc
228 @sa bt_clock_class_priority_map_get_clock_class_by_index(): Returns the clock
229 class contained in a given clock class priority map at
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.
237 struct bt_clock_class
*
238 bt_clock_class_priority_map_get_highest_priority_clock_class(
239 struct bt_clock_class_priority_map
*clock_class_priority_map
)
242 bt_clock_class_priority_map_borrow_highest_priority_clock_class(
243 clock_class_priority_map
));
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.
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
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
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}
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.
274 extern int bt_clock_class_priority_map_get_clock_class_priority(
275 struct bt_clock_class_priority_map
*clock_class_priority_map
,
276 struct bt_clock_class
*clock_class
, uint64_t *priority
);
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.
283 You can call this function even if \p clock_class is frozen.
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
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
297 @returns 0 on success, or a negative
300 @prenotnull{clock_class_priority_map}
301 @prenotnull{clock_class}
302 @prehot{clock_class_priority_map}
303 @postrefcountsame{clock_class_priority_map}
304 @postsuccessrefcountinc{clock_class}
306 @sa bt_clock_class_priority_map_get_clock_class_by_index(): Returns the clock
307 class contained in a given clock class priority map
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.
312 extern int bt_clock_class_priority_map_add_clock_class(
313 struct bt_clock_class_priority_map
*clock_class_priority_map
,
314 struct bt_clock_class
*clock_class
, uint64_t priority
);
317 @brief Creates a copy of the clock class priority map
318 \p clock_class_priority_map.
320 You can copy a frozen clock class priority map: the resulting copy is
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
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
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
);
343 #endif /* BABELTRACE_GRAPH_CLOCK_CLASS_PRIORITY_MAP_H */