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

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