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 | ||
59 | As with any Babeltrace object, clock class priority map objects have | |
60 | <a href="https://en.wikipedia.org/wiki/Reference_counting">reference | |
61 | counts</a>. See \ref refs to learn more about the reference counting | |
62 | management of Babeltrace objects. | |
63 | ||
64 | @file | |
65 | @brief Clock class priority map type and functions. | |
66 | @sa graphclockclassprioritymap | |
67 | ||
68 | @addtogroup graphclockclassprioritymap | |
69 | @{ | |
70 | */ | |
71 | ||
72 | /** | |
73 | @struct bt_clock_class_priority_map | |
74 | @brief A clock class priority map. | |
75 | @sa graphclockclassprioritymap | |
76 | */ | |
77 | struct bt_clock_class_priority_map; | |
78 | ||
79 | /** | |
80 | @brief Creates an empty clock class priority map. | |
81 | ||
82 | @returns Created clock class priority map object, or \c NULL on error. | |
83 | ||
84 | @postsuccessrefcountret1 | |
85 | */ | |
86 | extern struct bt_clock_class_priority_map *bt_clock_class_priority_map_create(); | |
87 | ||
88 | /** | |
89 | @brief Returns the number of CTF IR clock classes contained in the | |
90 | clock class priority map \p clock_class_priority_map. | |
91 | ||
92 | @param[in] clock_class_priority_map Clock class priority map of | |
93 | which to get the number of | |
94 | clock classes. | |
95 | @returns Number of clock classes contained | |
96 | in \p clock_class_priority_map, | |
97 | or a negative value on error. | |
98 | ||
99 | @prenotnull{clock_class_priority_map} | |
100 | @postrefcountsame{clock_class_priority_map} | |
101 | */ | |
102 | extern int bt_clock_class_priority_map_get_clock_class_count( | |
103 | struct bt_clock_class_priority_map *clock_class_priority_map); | |
104 | ||
105 | /** | |
106 | @brief Returns the CTF IR clock class at index \p index in the clock | |
107 | class priority map \p clock_class_priority_map. | |
108 | ||
109 | @param[in] clock_class_priority_map Clock class priority map of which | |
110 | to get the clock class at index | |
111 | \p index. | |
112 | @param[in] index Index of the clock class to find | |
113 | in \p clock_class_priority_map. | |
114 | @returns Clock class at index \p index in | |
115 | \p clock_class_priority_map, | |
116 | or \c NULL on error. | |
117 | ||
118 | @prenotnull{clock_class_priority_map} | |
119 | @pre \p index is lesser than the number of clock classes contained in | |
120 | the clock class priority map \p clock_class_priority_map (see | |
121 | bt_clock_class_priority_map_get_clock_class_count()). | |
122 | @postrefcountsame{clock_class_priority_map} | |
123 | ||
124 | @sa bt_clock_class_priority_map_get_clock_class_by_name(): Finds a clock | |
125 | class by name in a given clock class priority map. | |
126 | @sa bt_clock_class_priority_map_get_highest_priority_clock_class(): | |
127 | Returns the clock class with the highest priority contained | |
128 | in a given clock class priority map. | |
129 | @sa bt_clock_class_priority_map_add_clock_class(): Adds a clock class | |
130 | to a clock class priority map. | |
131 | */ | |
132 | extern struct bt_ctf_clock_class *bt_clock_class_priority_map_get_clock_class( | |
133 | struct bt_clock_class_priority_map *clock_class_priority_map, | |
134 | unsigned int index); | |
135 | ||
136 | /** | |
137 | @brief Returns the CTF IR clock class named \c name found in the clock | |
138 | class priority map \p clock_class_priority_map. | |
139 | ||
140 | @param[in] clock_class_priority_map Clock class priority map of | |
141 | which to get the clock class | |
142 | named \p name. | |
143 | @param[in] name Name of the clock class to find | |
144 | in \p clock_class_priority_map. | |
145 | @returns Clock class named \p name in | |
146 | \p clock_class_priority_map, | |
147 | or \c NULL on error. | |
148 | ||
149 | @prenotnull{clock_class_priority_map} | |
150 | @prenotnull{name} | |
151 | @postrefcountsame{clock_class_priority_map} | |
152 | @postsuccessrefcountretinc | |
153 | ||
154 | @sa bt_clock_class_priority_map_get_clock_class(): Returns the clock | |
155 | class contained in a given clock class priority map at | |
156 | a given index. | |
157 | @sa bt_clock_class_priority_map_get_highest_priority_clock_class(): | |
158 | Returns the clock class with the highest priority contained in | |
159 | a given clock class priority map. | |
160 | @sa bt_clock_class_priority_map_add_clock_class(): Adds a clock class | |
161 | to a clock class priority map. | |
162 | */ | |
163 | extern struct bt_ctf_clock_class * | |
164 | bt_clock_class_priority_map_get_clock_class_by_name( | |
165 | struct bt_clock_class_priority_map *clock_class_priority_map, | |
166 | const char *name); | |
167 | ||
168 | /** | |
169 | @brief Returns the CTF IR clock class with the currently highest | |
170 | priority within the clock class priority map | |
171 | \p clock_class_priority_map. | |
172 | ||
173 | If multiple clock classes share the same highest priority in | |
174 | \p clock_class_priority_map, you cannot deterministically know which one | |
175 | this function returns. | |
176 | ||
177 | @param[in] clock_class_priority_map Clock class priority map of which | |
178 | to get the clock class with the | |
179 | highest priority. | |
180 | @returns Clock class with the highest | |
181 | priority within | |
182 | \p clock_class_priority_map, or | |
183 | \c NULL on error or if there are | |
184 | no clock classes in | |
185 | \p clock_class_priority_map. | |
186 | ||
187 | @prenotnull{clock_class_priority_map} | |
188 | @postrefcountsame{clock_class_priority_map} | |
189 | @postsuccessrefcountretinc | |
190 | ||
191 | @sa bt_clock_class_priority_map_get_clock_class(): Returns the clock | |
192 | class contained in a given clock class priority map at | |
193 | a given index. | |
194 | @sa bt_clock_class_priority_map_get_clock_class_by_name(): Finds a | |
195 | clock class by name in a given clock class priority map. | |
196 | @sa bt_clock_class_priority_map_add_clock_class(): Adds a clock class | |
197 | to a clock class priority map. | |
198 | */ | |
199 | extern struct bt_ctf_clock_class * | |
200 | bt_clock_class_priority_map_get_highest_priority_clock_class( | |
201 | struct bt_clock_class_priority_map *clock_class_priority_map); | |
202 | ||
203 | /** | |
204 | @brief Returns the priority of the CTF IR clock class \p clock_class | |
205 | contained within the clock class priority map | |
206 | \p clock_class_priority_map. | |
207 | ||
208 | @param[in] clock_class_priority_map Clock class priority map | |
209 | containing \p clock_class. | |
210 | @param[in] clock_class Clock class of which to get the | |
211 | priority. | |
212 | @param[out] priority Returned priority of | |
213 | \p clock_class within | |
214 | \p clock_class_priority_map. | |
215 | @returns 0 on success, or a negative | |
216 | value on error. | |
217 | ||
218 | @prenotnull{clock_class_priority_map} | |
219 | @prenotnull{clock_class} | |
220 | @prenotnull{priority} | |
221 | @pre \p clock_class is contained in \p clock_class_priority_map (was | |
222 | previously added to \p clock_class_priority_map with | |
223 | bt_clock_class_priority_map_add_clock_class()). | |
224 | @postrefcountsame{clock_class_priority_map} | |
225 | @postrefcountsame{clock_class} | |
226 | ||
227 | @sa bt_clock_class_priority_map_get_highest_priority_clock_class(): | |
228 | Returns the clock class with the highest priority contained | |
229 | in a given clock class priority map. | |
230 | */ | |
231 | extern int bt_clock_class_priority_map_get_clock_class_priority( | |
232 | struct bt_clock_class_priority_map *clock_class_priority_map, | |
233 | struct bt_ctf_clock_class *clock_class, uint64_t *priority); | |
234 | ||
235 | /** | |
236 | @brief Adds the CTF IR clock class \p clock_class to the clock class | |
237 | priority map \p clock_class_priority_map with the | |
238 | priority \p priority. | |
239 | ||
240 | You can call this function even if \p clock_class is frozen. | |
241 | ||
242 | A lower priority value means a \em higher priority. Multiple clock | |
243 | classes can have the same priority within a given clock class priority | |
244 | map. | |
245 | ||
246 | @param[in] clock_class_priority_map Clock class priority map to | |
247 | which to add \p clock_class. | |
248 | @param[in] clock_class Clock class to add to | |
249 | \p clock_class_priority_map. | |
250 | @param[in] priority Priority of \p clock_class within | |
251 | \p clock_class_priority_map, | |
252 | where a lower value means a | |
253 | higher priority. | |
254 | @returns 0 on success, or a negative | |
255 | value on error. | |
256 | ||
257 | @prenotnull{clock_class_priority_map} | |
258 | @prenotnull{clock_class} | |
259 | @postrefcountsame{clock_class_priority_map} | |
260 | @postsuccessrefcountinc{clock_class} | |
261 | ||
262 | @sa bt_clock_class_priority_map_get_clock_class(): Returns the clock | |
263 | class contained in a given clock class priority map | |
264 | at a given index. | |
265 | @sa bt_clock_class_priority_map_get_clock_class_by_name(): Finds a | |
266 | clock class by name in a given clock class priority map. | |
267 | */ | |
268 | extern int bt_clock_class_priority_map_add_clock_class( | |
269 | struct bt_clock_class_priority_map *clock_class_priority_map, | |
270 | struct bt_ctf_clock_class *clock_class, uint64_t priority); | |
271 | ||
272 | /** @} */ | |
273 | ||
274 | #ifdef __cplusplus | |
275 | } | |
276 | #endif | |
277 | ||
278 | #endif /* BABELTRACE_GRAPH_CLOCK_CLASS_PRIORITY_MAP_H */ |