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> | |
8c0b8894 PP |
31 | |
32 | #ifdef __cplusplus | |
33 | extern "C" { | |
34 | #endif | |
35 | ||
9d408fca PP |
36 | struct bt_ctf_clock_class; |
37 | ||
8c0b8894 PP |
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 | */ | |
375d5f6a | 96 | extern struct bt_clock_class_priority_map *bt_clock_class_priority_map_create(void); |
8c0b8894 PP |
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 | */ | |
9ac68eb1 PP |
142 | extern struct bt_ctf_clock_class * |
143 | bt_clock_class_priority_map_get_clock_class_by_index( | |
8c0b8894 | 144 | struct bt_clock_class_priority_map *clock_class_priority_map, |
9ac68eb1 | 145 | uint64_t index); |
8c0b8894 PP |
146 | |
147 | /** | |
148 | @brief Returns the CTF IR clock class named \c name found in the clock | |
149 | class priority map \p clock_class_priority_map. | |
150 | ||
151 | @param[in] clock_class_priority_map Clock class priority map of | |
152 | which to get the clock class | |
153 | named \p name. | |
154 | @param[in] name Name of the clock class to find | |
155 | in \p clock_class_priority_map. | |
156 | @returns Clock class named \p name in | |
157 | \p clock_class_priority_map, | |
158 | or \c NULL on error. | |
159 | ||
160 | @prenotnull{clock_class_priority_map} | |
161 | @prenotnull{name} | |
162 | @postrefcountsame{clock_class_priority_map} | |
163 | @postsuccessrefcountretinc | |
164 | ||
9ac68eb1 | 165 | @sa bt_clock_class_priority_map_get_clock_class_by_index(): Returns the clock |
8c0b8894 PP |
166 | class contained in a given clock class priority map at |
167 | a given index. | |
168 | @sa bt_clock_class_priority_map_get_highest_priority_clock_class(): | |
169 | Returns the clock class with the highest priority contained in | |
170 | a given clock class priority map. | |
171 | @sa bt_clock_class_priority_map_add_clock_class(): Adds a clock class | |
172 | to a clock class priority map. | |
173 | */ | |
174 | extern struct bt_ctf_clock_class * | |
175 | bt_clock_class_priority_map_get_clock_class_by_name( | |
176 | struct bt_clock_class_priority_map *clock_class_priority_map, | |
177 | const char *name); | |
178 | ||
179 | /** | |
180 | @brief Returns the CTF IR clock class with the currently highest | |
181 | priority within the clock class priority map | |
182 | \p clock_class_priority_map. | |
183 | ||
184 | If multiple clock classes share the same highest priority in | |
185 | \p clock_class_priority_map, you cannot deterministically know which one | |
186 | this function returns. | |
187 | ||
188 | @param[in] clock_class_priority_map Clock class priority map of which | |
189 | to get the clock class with the | |
190 | highest priority. | |
191 | @returns Clock class with the highest | |
192 | priority within | |
193 | \p clock_class_priority_map, or | |
194 | \c NULL on error or if there are | |
195 | no clock classes in | |
196 | \p clock_class_priority_map. | |
197 | ||
198 | @prenotnull{clock_class_priority_map} | |
199 | @postrefcountsame{clock_class_priority_map} | |
200 | @postsuccessrefcountretinc | |
201 | ||
9ac68eb1 | 202 | @sa bt_clock_class_priority_map_get_clock_class_by_index(): Returns the clock |
8c0b8894 PP |
203 | class contained in a given clock class priority map at |
204 | a given index. | |
205 | @sa bt_clock_class_priority_map_get_clock_class_by_name(): Finds a | |
206 | clock class by name in a given clock class priority map. | |
207 | @sa bt_clock_class_priority_map_add_clock_class(): Adds a clock class | |
208 | to a clock class priority map. | |
209 | */ | |
210 | extern struct bt_ctf_clock_class * | |
211 | bt_clock_class_priority_map_get_highest_priority_clock_class( | |
212 | struct bt_clock_class_priority_map *clock_class_priority_map); | |
213 | ||
214 | /** | |
215 | @brief Returns the priority of the CTF IR clock class \p clock_class | |
216 | contained within the clock class priority map | |
217 | \p clock_class_priority_map. | |
218 | ||
219 | @param[in] clock_class_priority_map Clock class priority map | |
220 | containing \p clock_class. | |
221 | @param[in] clock_class Clock class of which to get the | |
222 | priority. | |
223 | @param[out] priority Returned priority of | |
224 | \p clock_class within | |
225 | \p clock_class_priority_map. | |
226 | @returns 0 on success, or a negative | |
227 | value on error. | |
228 | ||
229 | @prenotnull{clock_class_priority_map} | |
230 | @prenotnull{clock_class} | |
231 | @prenotnull{priority} | |
232 | @pre \p clock_class is contained in \p clock_class_priority_map (was | |
233 | previously added to \p clock_class_priority_map with | |
234 | bt_clock_class_priority_map_add_clock_class()). | |
235 | @postrefcountsame{clock_class_priority_map} | |
236 | @postrefcountsame{clock_class} | |
237 | ||
238 | @sa bt_clock_class_priority_map_get_highest_priority_clock_class(): | |
239 | Returns the clock class with the highest priority contained | |
240 | in a given clock class priority map. | |
241 | */ | |
242 | extern int bt_clock_class_priority_map_get_clock_class_priority( | |
243 | struct bt_clock_class_priority_map *clock_class_priority_map, | |
244 | struct bt_ctf_clock_class *clock_class, uint64_t *priority); | |
245 | ||
246 | /** | |
247 | @brief Adds the CTF IR clock class \p clock_class to the clock class | |
248 | priority map \p clock_class_priority_map with the | |
249 | priority \p priority. | |
250 | ||
251 | You can call this function even if \p clock_class is frozen. | |
252 | ||
253 | A lower priority value means a \em higher priority. Multiple clock | |
254 | classes can have the same priority within a given clock class priority | |
255 | map. | |
256 | ||
257 | @param[in] clock_class_priority_map Clock class priority map to | |
258 | which to add \p clock_class. | |
259 | @param[in] clock_class Clock class to add to | |
260 | \p clock_class_priority_map. | |
261 | @param[in] priority Priority of \p clock_class within | |
262 | \p clock_class_priority_map, | |
263 | where a lower value means a | |
264 | higher priority. | |
265 | @returns 0 on success, or a negative | |
266 | value on error. | |
267 | ||
268 | @prenotnull{clock_class_priority_map} | |
269 | @prenotnull{clock_class} | |
fe650ea4 | 270 | @prehot{clock_class_priority_map} |
8c0b8894 PP |
271 | @postrefcountsame{clock_class_priority_map} |
272 | @postsuccessrefcountinc{clock_class} | |
273 | ||
9ac68eb1 | 274 | @sa bt_clock_class_priority_map_get_clock_class_by_index(): Returns the clock |
8c0b8894 PP |
275 | class contained in a given clock class priority map |
276 | at a given index. | |
277 | @sa bt_clock_class_priority_map_get_clock_class_by_name(): Finds a | |
278 | clock class by name in a given clock class priority map. | |
279 | */ | |
280 | extern int bt_clock_class_priority_map_add_clock_class( | |
281 | struct bt_clock_class_priority_map *clock_class_priority_map, | |
282 | struct bt_ctf_clock_class *clock_class, uint64_t priority); | |
283 | ||
7b5d7f76 PP |
284 | /** |
285 | @brief Creates a copy of the clock class priority map | |
286 | \p clock_class_priority_map. | |
287 | ||
288 | You can copy a frozen clock class priority map: the resulting copy is | |
289 | <em>not frozen</em>. | |
290 | ||
291 | @param[in] clock_class_priority_map Clock class priority map to copy. | |
292 | @returns Copy of \p clock_class_priority_map | |
293 | on success, or a negative value | |
294 | on error. | |
295 | ||
296 | @prenotnull{clock_class_priority_map} | |
297 | @postrefcountsame{clock_class_priority_map} | |
298 | @postsuccessrefcountret1 | |
299 | @post <strong>On success</strong>, the returned clock class priority map | |
300 | is not frozen. | |
301 | */ | |
302 | extern struct bt_clock_class_priority_map *bt_clock_class_priority_map_copy( | |
303 | struct bt_clock_class_priority_map *clock_class_priority_map); | |
304 | ||
8c0b8894 PP |
305 | /** @} */ |
306 | ||
307 | #ifdef __cplusplus | |
308 | } | |
309 | #endif | |
310 | ||
311 | #endif /* BABELTRACE_GRAPH_CLOCK_CLASS_PRIORITY_MAP_H */ |