include/babeltrace/graph/clock-class-priority-map.h

   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 /* For bt_get() */
  30 #include <babeltrace/ref.h>
  31
  32 #include <stdint.h>
  33 #include <stddef.h>
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 struct bt_clock_class;
  40
  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
  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
  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 */
  99 extern struct bt_clock_class_priority_map *bt_clock_class_priority_map_create(void);
 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 */
 115 extern int64_t bt_clock_class_priority_map_get_clock_class_count(
 116                 struct bt_clock_class_priority_map *clock_class_priority_map);
 117
 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
 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 */
 150 static inline
 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,
 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);
 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
 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
 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 */
 192 static inline
 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,
 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);
 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
 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
 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 */
 236 static inline
 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)
 240 {
 241         return bt_get(
 242                 bt_clock_class_priority_map_borrow_highest_priority_clock_class(
 243                         clock_class_priority_map));
 244 }
 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,
 276                 struct bt_clock_class *clock_class, uint64_t *priority);
 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}
 302 @prehot{clock_class_priority_map}
 303 @postrefcountsame{clock_class_priority_map}
 304 @postsuccessrefcountinc{clock_class}
 305
 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
 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,
 314                 struct bt_clock_class *clock_class, uint64_t priority);
 315
 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
 337 /** @} */
 338
 339 #ifdef __cplusplus
 340 }
 341 #endif
 342
 343 #endif /* BABELTRACE_GRAPH_CLOCK_CLASS_PRIORITY_MAP_H */