include/babeltrace2/graph/component-descriptor-set.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H
   8 #define BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H
   9
  10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
  11
  12 #ifndef __BT_IN_BABELTRACE_H
  13 # error "Please include <babeltrace2/babeltrace.h> instead."
  14 #endif
  15
  16 #include <babeltrace2/types.h>
  17 #include <babeltrace2/logging.h>
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 /*!
  24 @defgroup api-comp-descr-set Component descriptor set
  25 @ingroup api-graph
  26
  27 @brief
  28     Set of descriptors of prospective \bt_p_comp to use with
  29     bt_get_greatest_operative_mip_version().
  30
  31 A <strong><em>component descriptor set</em></strong>
  32 is an \em unordered set of component descriptors.
  33
  34 A <strong><em>component descriptor</em></strong> describes a
  35 prospective \bt_comp, that is, everything that is needed to
  36 \ref api-graph-lc-add "instantiate a component class" within a
  37 trace processing \bt_graph without actually doing it:
  38
  39 - The <strong>component class</strong> to instantiate, which you would
  40   pass as the \bt_p{component_class} parameter of one of the
  41   <code>bt_graph_add_*_component*()</code> functions.
  42
  43 - The <strong>initialization parameters</strong>, which you
  44   would pass as the \bt_p{params} parameter of one of the
  45   <code>bt_graph_add_*_component*()</code> functions.
  46
  47 - The <strong>initialization method data</strong>, which you would pass
  48   as the \bt_p{initialize_method_data} parameter of one of the
  49   <code>bt_graph_add_*_component_with_initialize_method_data()</code>
  50   functions.
  51
  52 As of \bt_name_version_min_maj, the only use case of a component
  53 descriptor set is bt_get_greatest_operative_mip_version(). This
  54 function computes the greatest \bt_mip version which
  55 you can use to create a trace processing graph to which you intend
  56 to \ref api-graph-lc-add "add components" described by a set of
  57 component descriptors.
  58
  59 A component descriptor set is a
  60 \ref api-fund-shared-object "shared object": get a new reference with
  61 bt_component_descriptor_set_get_ref() and put an existing reference with
  62 bt_component_descriptor_set_put_ref().
  63
  64 Create an empty component descriptor set with
  65 bt_component_descriptor_set_create().
  66
  67 Add a component descriptor to a component descriptor set with
  68 bt_component_descriptor_set_add_descriptor() and
  69 bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
  70 */
  71
  72 /*! @{ */
  73
  74 /*!
  75 @name Type
  76 @{
  77
  78 @typedef struct bt_component_descriptor_set bt_component_descriptor_set;
  79
  80 @brief
  81     Component descriptor set.
  82
  83 @}
  84 */
  85
  86 /*!
  87 @name Creation
  88 @{
  89 */
  90
  91 /*!
  92 @brief
  93     Creates an empty component descriptor set.
  94
  95 @returns
  96     New component descriptor set reference, or \c NULL on memory error.
  97 */
  98 extern bt_component_descriptor_set *bt_component_descriptor_set_create(void)
  99                 __BT_NOEXCEPT;
 100
 101 /*!
 102 @brief
 103     Status codes for bt_component_descriptor_set_add_descriptor()
 104     and
 105     bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
 106 */
 107 typedef enum bt_component_descriptor_set_add_descriptor_status {
 108         /*!
 109         @brief
 110             Success.
 111         */
 112         BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK            = __BT_FUNC_STATUS_OK,
 113
 114         /*!
 115         @brief
 116             Out of memory.
 117         */
 118         BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
 119 } bt_component_descriptor_set_add_descriptor_status;
 120
 121 /*! @} */
 122
 123 /*!
 124 @name Component descriptor adding
 125 @{
 126 */
 127
 128 /*!
 129 @brief
 130     Alias of
 131     bt_component_descriptor_set_add_descriptor_with_initialize_method_data()
 132     with the \bt_p{initialize_method_data} parameter set to \c NULL.
 133 */
 134 extern bt_component_descriptor_set_add_descriptor_status
 135 bt_component_descriptor_set_add_descriptor(
 136                 bt_component_descriptor_set *component_descriptor_set,
 137                 const bt_component_class *component_class,
 138                 const bt_value *params) __BT_NOEXCEPT;
 139
 140 /*!
 141 @brief
 142     Adds a descriptor of a \bt_comp which would be an instance of the
 143     \bt_comp_cls \bt_p{component_class}, would receive the parameters
 144     \bt_p{params} and the method data \bt_p{initialize_method_data} at
 145     initialization time, to the component descriptor set
 146     \bt_p{component_descriptor_set}.
 147
 148 @param[in] component_descriptor_set
 149     Component descriptor set to which to add a component descriptor.
 150 @param[in] component_class
 151     \bt_c_comp_cls which would be instantiated to create the
 152     described component.
 153 @param[in] params
 154     @parblock
 155     Parameters which would be passed to the initialization method of
 156     the described component as the \bt_p{params} parameter.
 157
 158     Can be \c NULL, in which case it is equivalent to passing an empty
 159     \bt_map_val.
 160     @endparblock
 161 @param[in] initialize_method_data
 162     User data which would be passed to the initialization method of
 163     the described component as the \bt_p{initialize_method_data}
 164     parameter.
 165
 166 @retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK
 167     Success.
 168 @retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR
 169     Out of memory.
 170
 171 @bt_pre_not_null{component_descriptor_set}
 172 @bt_pre_not_null{component_class}
 173 @pre
 174     \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
 175     or is \c NULL.
 176
 177 @bt_post_success_frozen{component_class}
 178 @bt_post_success_frozen{params}
 179 */
 180 extern bt_component_descriptor_set_add_descriptor_status
 181 bt_component_descriptor_set_add_descriptor_with_initialize_method_data(
 182                 bt_component_descriptor_set *component_descriptor_set,
 183                 const bt_component_class *component_class,
 184                 const bt_value *params,
 185                 void *initialize_method_data) __BT_NOEXCEPT;
 186
 187 /*! @} */
 188
 189 /*!
 190 @name Reference count
 191 @{
 192 */
 193
 194 /*!
 195 @brief
 196     Increments the \ref api-fund-shared-object "reference count" of
 197     the component descriptor set \bt_p{component_descriptor_set}.
 198
 199 @param[in] component_descriptor_set
 200     @parblock
 201     Component descriptor set of which to increment the reference count.
 202
 203     Can be \c NULL.
 204     @endparblock
 205
 206 @sa bt_component_descriptor_set_put_ref() &mdash;
 207     Decrements the reference count of a component descriptor set.
 208 */
 209 extern void bt_component_descriptor_set_get_ref(
 210                 const bt_component_descriptor_set *component_descriptor_set)
 211                 __BT_NOEXCEPT;
 212
 213 /*!
 214 @brief
 215     Decrements the \ref api-fund-shared-object "reference count" of
 216     the component descriptor set \bt_p{component_descriptor_set}.
 217
 218 @param[in] component_descriptor_set
 219     @parblock
 220     Component descriptor set of which to decrement the reference count.
 221
 222     Can be \c NULL.
 223     @endparblock
 224
 225 @sa bt_component_descriptor_set_get_ref() &mdash;
 226     Increments the reference count of a component descriptor set.
 227 */
 228 extern void bt_component_descriptor_set_put_ref(
 229                 const bt_component_descriptor_set *component_descriptor_set)
 230                 __BT_NOEXCEPT;
 231
 232 /*!
 233 @brief
 234     Decrements the reference count of the component descriptor set
 235     \bt_p{_component_descriptor_set}, and then sets
 236     \bt_p{_component_descriptor_set} to \c NULL.
 237
 238 @param _component_descriptor_set
 239     @parblock
 240     Component descriptor set of which to decrement the reference count.
 241
 242     Can contain \c NULL.
 243     @endparblock
 244
 245 @bt_pre_assign_expr{_component_descriptor_set}
 246 */
 247 #define BT_COMPONENT_DESCRIPTOR_SET_PUT_REF_AND_RESET(_component_descriptor_set) \
 248         do {                                                            \
 249                 bt_component_descriptor_set_put_ref(_component_descriptor_set); \
 250                 (_component_descriptor_set) = NULL;                     \
 251         } while (0)
 252
 253 /*!
 254 @brief
 255     Decrements the reference count of the component descriptor set
 256     \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
 257     \bt_p{_src} to \c NULL.
 258
 259 This macro effectively moves a component descriptor set reference from
 260 the expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
 261 existing \bt_p{_dst} reference.
 262
 263 @param _dst
 264     @parblock
 265     Destination expression.
 266
 267     Can contain \c NULL.
 268     @endparblock
 269 @param _src
 270     @parblock
 271     Source expression.
 272
 273     Can contain \c NULL.
 274     @endparblock
 275
 276 @bt_pre_assign_expr{_dst}
 277 @bt_pre_assign_expr{_src}
 278 */
 279 #define BT_COMPONENT_DESCRIPTOR_SET_MOVE_REF(_dst, _src)        \
 280         do {                                                    \
 281                 bt_component_descriptor_set_put_ref(_dst);      \
 282                 (_dst) = (_src);                                \
 283                 (_src) = NULL;                                  \
 284         } while (0)
 285
 286 /*! @} */
 287
 288 /*! @} */
 289
 290 #ifdef __cplusplus
 291 }
 292 #endif
 293
 294 #endif /* BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H */