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