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(void);
  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 *
 143 bt_clock_class_priority_map_get_clock_class_by_index(
 144                 struct bt_clock_class_priority_map *clock_class_priority_map,
 145                 uint64_t index);
 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
 165 @sa bt_clock_class_priority_map_get_clock_class_by_index(): Returns the clock
 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
 202 @sa bt_clock_class_priority_map_get_clock_class_by_index(): Returns the clock
 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}
 270 @prehot{clock_class_priority_map}
 271 @postrefcountsame{clock_class_priority_map}
 272 @postsuccessrefcountinc{clock_class}
 273
 274 @sa bt_clock_class_priority_map_get_clock_class_by_index(): Returns the clock
 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
 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
 305 /** @} */
 306
 307 #ifdef __cplusplus
 308 }
 309 #endif
 310
 311 #endif /* BABELTRACE_GRAPH_CLOCK_CLASS_PRIORITY_MAP_H */