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

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