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