include/babeltrace2/graph/self-component-port.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_PORT_H
   8 #define BABELTRACE2_GRAPH_SELF_COMPONENT_PORT_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
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif
  19
  20 /*!
  21 @defgroup api-self-comp-port Self component ports
  22 @ingroup api-self-comp
  23
  24 @brief
  25     Private views of \bt_p_port for \bt_comp_cls instance methods.
  26
  27 The #bt_self_component_port, #bt_self_component_port_input, and
  28 #bt_self_component_port_output types are private views of a \bt_port
  29 from within a component class
  30 \ref api-comp-cls-dev-instance-meth "instance method".
  31
  32 Borrow the \bt_self_comp of a port with
  33 bt_self_component_port_borrow_component().
  34
  35 Get the user data attached to a port with
  36 bt_self_component_port_get_data().
  37
  38 \ref api-fund-c-typing "Upcast" the "self" (private) types to the
  39 public and common self component port types with the
  40 <code>bt_self_component_port*_as_port*()</code> and
  41 <code>bt_self_component_port_*_as_self_component_port()</code>
  42 functions.
  43 */
  44
  45 /*! @{ */
  46
  47 /*!
  48 @name Types
  49 @{
  50
  51 @typedef struct bt_self_component_port bt_self_component_port;
  52
  53 @brief
  54     Self component \bt_comp.
  55
  56 @typedef struct bt_self_component_port_input bt_self_component_port_input;
  57
  58 @brief
  59     Self component \bt_iport.
  60
  61 @typedef struct bt_self_component_port_output bt_self_component_port_output;
  62
  63 @brief
  64     Self component \bt_oport.
  65
  66 @}
  67 */
  68
  69 /*!
  70 @name Component access
  71 @{
  72 */
  73
  74 /*!
  75 @brief
  76     Borrows the \bt_comp of the \bt_port \bt_p{self_component_port}.
  77
  78 @param[in] self_component_port
  79     Port from which to borrow the component which owns it.
  80
  81 @returns
  82     Component which owns \bt_p{self_component_port}.
  83
  84 @bt_pre_not_null{self_component_port}
  85 */
  86 extern bt_self_component *bt_self_component_port_borrow_component(
  87                 bt_self_component_port *self_component_port);
  88
  89 /*! @} */
  90
  91 /*!
  92 @name User data access
  93 @{
  94 */
  95
  96 /*!
  97 @brief
  98     Returns the user data of the \bt_port \bt_p{self_component_port}.
  99
 100 You can attach user data to a port when you add it to a component with
 101 bt_self_component_source_add_output_port(),
 102 bt_self_component_filter_add_input_port(),
 103 bt_self_component_filter_add_output_port(), and
 104 bt_self_component_sink_add_input_port().
 105
 106 @param[in] self_component_port
 107     Port of which to get the user data.
 108
 109 @returns
 110     User data of \bt_p{self_component_port}.
 111
 112 @bt_pre_not_null{self_component_port}
 113 */
 114 extern void *bt_self_component_port_get_data(
 115                 const bt_self_component_port *self_component_port);
 116
 117 /*! @} */
 118
 119 /*!
 120 @name Self to public upcast
 121 @{
 122 */
 123
 124 /*!
 125 @brief
 126     \ref api-fund-c-typing "Upcasts" the self component port
 127     \bt_p{self_component_port} to the public #bt_port type.
 128
 129 @param[in] self_component_port
 130     @parblock
 131     Port to upcast.
 132
 133     Can be \c NULL.
 134     @endparblock
 135
 136 @returns
 137     \bt_p{self_component_port} as a public port.
 138 */
 139 static inline
 140 const bt_port *bt_self_component_port_as_port(
 141                 bt_self_component_port *self_component_port)
 142 {
 143         return __BT_UPCAST_CONST(bt_port, self_component_port);
 144 }
 145
 146 /*!
 147 @brief
 148     \ref api-fund-c-typing "Upcasts" the self component \bt_iport
 149     \bt_p{self_component_port} to the public #bt_port_input type.
 150
 151 @param[in] self_component_port
 152     @parblock
 153     Input port to upcast.
 154
 155     Can be \c NULL.
 156     @endparblock
 157
 158 @returns
 159     \bt_p{self_component_port} as a public input port.
 160 */
 161 static inline
 162 const bt_port_input *bt_self_component_port_input_as_port_input(
 163                 const bt_self_component_port_input *self_component_port)
 164 {
 165         return __BT_UPCAST_CONST(bt_port_input, self_component_port);
 166 }
 167
 168 /*!
 169 @brief
 170     \ref api-fund-c-typing "Upcasts" the self component \bt_oport
 171     \bt_p{self_component_port} to the public #bt_port_output type.
 172
 173 @param[in] self_component_port
 174     @parblock
 175     Output port to upcast.
 176
 177     Can be \c NULL.
 178     @endparblock
 179
 180 @returns
 181     \bt_p{self_component_port} as a public output port.
 182 */
 183 static inline
 184 const bt_port_output *bt_self_component_port_output_as_port_output(
 185                 bt_self_component_port_output *self_component_port)
 186 {
 187         return __BT_UPCAST_CONST(bt_port_output, self_component_port);
 188 }
 189
 190 /*! @} */
 191
 192 /*!
 193 @name Self to common self upcast
 194 @{
 195 */
 196
 197 /*!
 198 @brief
 199     \ref api-fund-c-typing "Upcasts" the self \bt_iport
 200     \bt_p{self_component_port} to the common #bt_self_component_port
 201     type.
 202
 203 @param[in] self_component_port
 204     @parblock
 205     Input port to upcast.
 206
 207     Can be \c NULL.
 208     @endparblock
 209
 210 @returns
 211     \bt_p{self_component_port} as a common self component port.
 212 */
 213 static inline
 214 bt_self_component_port *
 215 bt_self_component_port_input_as_self_component_port(
 216                 bt_self_component_port_input *self_component_port)
 217 {
 218         return __BT_UPCAST(bt_self_component_port, self_component_port);
 219 }
 220
 221 /*!
 222 @brief
 223     \ref api-fund-c-typing "Upcasts" the self \bt_oport
 224     \bt_p{self_component_port} to the common #bt_self_component_port
 225     type.
 226
 227 @param[in] self_component_port
 228     @parblock
 229     Output port to upcast.
 230
 231     Can be \c NULL.
 232     @endparblock
 233
 234 @returns
 235     \bt_p{self_component_port} as a common self component port.
 236 */
 237 static inline
 238 bt_self_component_port *
 239 bt_self_component_port_output_as_self_component_port(
 240                 bt_self_component_port_output *self_component_port)
 241 {
 242         return __BT_UPCAST(bt_self_component_port, self_component_port);
 243 }
 244
 245 /*! @} */
 246
 247 /*! @} */
 248
 249 #ifdef __cplusplus
 250 }
 251 #endif
 252
 253 #endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_PORT_H */