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