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 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 */