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) __BT_NOEXCEPT;
  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                 __BT_NOEXCEPT;
 119
 120 /*! @} */
 121
 122 /*!
 123 @name Self to public upcast
 124 @{
 125 */
 126
 127 /*!
 128 @brief
 129     \ref api-fund-c-typing "Upcasts" the self component port
 130     \bt_p{self_component_port} to the public #bt_port type.
 131
 132 @param[in] self_component_port
 133     @parblock
 134     Port to upcast.
 135
 136     Can be \c NULL.
 137     @endparblock
 138
 139 @returns
 140     \bt_p{self_component_port} as a public port.
 141 */
 142 static inline
 143 const bt_port *bt_self_component_port_as_port(
 144                 bt_self_component_port *self_component_port) __BT_NOEXCEPT
 145 {
 146         return __BT_UPCAST_CONST(bt_port, self_component_port);
 147 }
 148
 149 /*!
 150 @brief
 151     \ref api-fund-c-typing "Upcasts" the self component \bt_iport
 152     \bt_p{self_component_port} to the public #bt_port_input type.
 153
 154 @param[in] self_component_port
 155     @parblock
 156     Input port to upcast.
 157
 158     Can be \c NULL.
 159     @endparblock
 160
 161 @returns
 162     \bt_p{self_component_port} as a public input port.
 163 */
 164 static inline
 165 const bt_port_input *bt_self_component_port_input_as_port_input(
 166                 const bt_self_component_port_input *self_component_port)
 167                 __BT_NOEXCEPT
 168 {
 169         return __BT_UPCAST_CONST(bt_port_input, self_component_port);
 170 }
 171
 172 /*!
 173 @brief
 174     \ref api-fund-c-typing "Upcasts" the self component \bt_oport
 175     \bt_p{self_component_port} to the public #bt_port_output type.
 176
 177 @param[in] self_component_port
 178     @parblock
 179     Output port to upcast.
 180
 181     Can be \c NULL.
 182     @endparblock
 183
 184 @returns
 185     \bt_p{self_component_port} as a public output port.
 186 */
 187 static inline
 188 const bt_port_output *bt_self_component_port_output_as_port_output(
 189                 bt_self_component_port_output *self_component_port)
 190                 __BT_NOEXCEPT
 191 {
 192         return __BT_UPCAST_CONST(bt_port_output, self_component_port);
 193 }
 194
 195 /*! @} */
 196
 197 /*!
 198 @name Self to common self upcast
 199 @{
 200 */
 201
 202 /*!
 203 @brief
 204     \ref api-fund-c-typing "Upcasts" the self \bt_iport
 205     \bt_p{self_component_port} to the common #bt_self_component_port
 206     type.
 207
 208 @param[in] self_component_port
 209     @parblock
 210     Input port to upcast.
 211
 212     Can be \c NULL.
 213     @endparblock
 214
 215 @returns
 216     \bt_p{self_component_port} as a common self component port.
 217 */
 218 static inline
 219 bt_self_component_port *
 220 bt_self_component_port_input_as_self_component_port(
 221                 bt_self_component_port_input *self_component_port)
 222                 __BT_NOEXCEPT
 223 {
 224         return __BT_UPCAST(bt_self_component_port, self_component_port);
 225 }
 226
 227 /*!
 228 @brief
 229     \ref api-fund-c-typing "Upcasts" the self \bt_oport
 230     \bt_p{self_component_port} to the common #bt_self_component_port
 231     type.
 232
 233 @param[in] self_component_port
 234     @parblock
 235     Output port to upcast.
 236
 237     Can be \c NULL.
 238     @endparblock
 239
 240 @returns
 241     \bt_p{self_component_port} as a common self component port.
 242 */
 243 static inline
 244 bt_self_component_port *
 245 bt_self_component_port_output_as_self_component_port(
 246                 bt_self_component_port_output *self_component_port)
 247                 __BT_NOEXCEPT
 248 {
 249         return __BT_UPCAST(bt_self_component_port, self_component_port);
 250 }
 251
 252 /*! @} */
 253
 254 /*! @} */
 255
 256 #ifdef __cplusplus
 257 }
 258 #endif
 259
 260 #endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_PORT_H */