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
 100 /*!
 101 @brief
 102     Status codes for bt_component_descriptor_set_add_descriptor()
 103     and
 104     bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
 105 */
 106 typedef enum bt_component_descriptor_set_add_descriptor_status {
 107         /*!
 108         @brief
 109             Success.
 110         */
 111         BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK            = __BT_FUNC_STATUS_OK,
 112
 113         /*!
 114         @brief
 115             Out of memory.
 116         */
 117         BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
 118 } bt_component_descriptor_set_add_descriptor_status;
 119
 120 /*! @} */
 121
 122 /*!
 123 @name Component descriptor adding
 124 @{
 125 */
 126
 127 /*!
 128 @brief
 129     Alias of
 130     bt_component_descriptor_set_add_descriptor_with_initialize_method_data()
 131     with the \bt_p{initialize_method_data} parameter set to \c NULL.
 132 */
 133 extern bt_component_descriptor_set_add_descriptor_status
 134 bt_component_descriptor_set_add_descriptor(
 135                 bt_component_descriptor_set *component_descriptor_set,
 136                 const bt_component_class *component_class,
 137                 const bt_value *params);
 138
 139 /*!
 140 @brief
 141     Adds a descriptor of a \bt_comp which would be an instance of the
 142     \bt_comp_cls \bt_p{component_class}, would receive the parameters
 143     \bt_p{params} and the method data \bt_p{initialize_method_data} at
 144     initialization time, to the component descriptor set
 145     \bt_p{component_descriptor_set}.
 146
 147 @param[in] component_descriptor_set
 148     Component descriptor set to which to add a component descriptor.
 149 @param[in] component_class
 150     \bt_c_comp_cls which would be instantiated to create the
 151     described component.
 152 @param[in] params
 153     @parblock
 154     Parameters which would be passed to the initialization method of
 155     the described component as the \bt_p{params} parameter.
 156
 157     Can be \c NULL, in which case it is equivalent to passing an empty
 158     \bt_map_val.
 159     @endparblock
 160 @param[in] initialize_method_data
 161     User data which would be passed to the initialization method of
 162     the described component as the \bt_p{initialize_method_data}
 163     parameter.
 164
 165 @retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK
 166     Success.
 167 @retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR
 168     Out of memory.
 169
 170 @bt_pre_not_null{component_descriptor_set}
 171 @bt_pre_not_null{component_class}
 172 @pre
 173     \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
 174     or is \c NULL.
 175
 176 @bt_post_success_frozen{component_class}
 177 @bt_post_success_frozen{params}
 178 */
 179 extern bt_component_descriptor_set_add_descriptor_status
 180 bt_component_descriptor_set_add_descriptor_with_initialize_method_data(
 181                 bt_component_descriptor_set *component_descriptor_set,
 182                 const bt_component_class *component_class,
 183                 const bt_value *params, void *initialize_method_data);
 184
 185 /*! @} */
 186
 187 /*!
 188 @name Reference count
 189 @{
 190 */
 191
 192 /*!
 193 @brief
 194     Increments the \ref api-fund-shared-object "reference count" of
 195     the component descriptor set \bt_p{component_descriptor_set}.
 196
 197 @param[in] component_descriptor_set
 198     @parblock
 199     Component descriptor set of which to increment the reference count.
 200
 201     Can be \c NULL.
 202     @endparblock
 203
 204 @sa bt_component_descriptor_set_put_ref() &mdash;
 205     Decrements the reference count of a component descriptor set.
 206 */
 207 extern void bt_component_descriptor_set_get_ref(
 208                 const bt_component_descriptor_set *component_descriptor_set);
 209
 210 /*!
 211 @brief
 212     Decrements the \ref api-fund-shared-object "reference count" of
 213     the component descriptor set \bt_p{component_descriptor_set}.
 214
 215 @param[in] component_descriptor_set
 216     @parblock
 217     Component descriptor set of which to decrement the reference count.
 218
 219     Can be \c NULL.
 220     @endparblock
 221
 222 @sa bt_component_descriptor_set_get_ref() &mdash;
 223     Increments the reference count of a component descriptor set.
 224 */
 225 extern void bt_component_descriptor_set_put_ref(
 226                 const bt_component_descriptor_set *component_descriptor_set);
 227
 228 /*!
 229 @brief
 230     Decrements the reference count of the component descriptor set
 231     \bt_p{_component_descriptor_set}, and then sets
 232     \bt_p{_component_descriptor_set} to \c NULL.
 233
 234 @param _component_descriptor_set
 235     @parblock
 236     Component descriptor set of which to decrement the reference count.
 237
 238     Can contain \c NULL.
 239     @endparblock
 240
 241 @bt_pre_assign_expr{_component_descriptor_set}
 242 */
 243 #define BT_COMPONENT_DESCRIPTOR_SET_PUT_REF_AND_RESET(_component_descriptor_set) \
 244         do {                                                            \
 245                 bt_component_descriptor_set_put_ref(_component_descriptor_set); \
 246                 (_component_descriptor_set) = NULL;                     \
 247         } while (0)
 248
 249 /*!
 250 @brief
 251     Decrements the reference count of the component descriptor set
 252     \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
 253     \bt_p{_src} to \c NULL.
 254
 255 This macro effectively moves a component descriptor set reference from
 256 the expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
 257 existing \bt_p{_dst} reference.
 258
 259 @param _dst
 260     @parblock
 261     Destination expression.
 262
 263     Can contain \c NULL.
 264     @endparblock
 265 @param _src
 266     @parblock
 267     Source expression.
 268
 269     Can contain \c NULL.
 270     @endparblock
 271
 272 @bt_pre_assign_expr{_dst}
 273 @bt_pre_assign_expr{_src}
 274 */
 275 #define BT_COMPONENT_DESCRIPTOR_SET_MOVE_REF(_dst, _src)        \
 276         do {                                                    \
 277                 bt_component_descriptor_set_put_ref(_dst);      \
 278                 (_dst) = (_src);                                \
 279                 (_src) = NULL;                                  \
 280         } while (0)
 281
 282 /*! @} */
 283
 284 /*! @} */
 285
 286 #ifdef __cplusplus
 287 }
 288 #endif
 289
 290 #endif /* BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_H */