include/babeltrace2: add `noexcept` specifier for C++ ≥ 11
[babeltrace.git] / include / babeltrace2 / graph / connection.h
1 /*
2 * SPDX-License-Identifier: MIT
3 *
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
5 */
6
7 #ifndef BABELTRACE2_GRAPH_CONNECTION_H
8 #define BABELTRACE2_GRAPH_CONNECTION_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-conn Connection
24 @ingroup api-graph
25
26 @brief
27 \bt_c_comp \bt_port connection.
28
29 A <strong><em>connection</em></strong> is a link between an \bt_oport
30 and an \bt_iport.
31
32 @image html component-zoom.png
33
34 A connection is a \ref api-fund-shared-object "shared object": get a new
35 reference with bt_connection_get_ref() and put an existing reference with
36 bt_connection_put_ref().
37
38 The type of a connection is #bt_connection.
39
40 Borrow the upstream (output) port and downstream (input) port of a
41 connection with bt_connection_borrow_upstream_port_const() and
42 bt_connection_borrow_downstream_port_const().
43 */
44
45 /*! @{ */
46
47 /*!
48 @name Type
49 @{
50
51 @typedef struct bt_connection bt_connection;
52
53 @brief
54 Connection.
55
56 @}
57 */
58
59 /*!
60 @name Port access
61 @{
62 */
63
64 /*!
65 @brief
66 Borrows the upstream \bt_iport of the connection \bt_p{connection}.
67
68 @param[in] connection
69 Connection of which to borrow the upstream port.
70
71 @returns
72 \em Borrowed reference of the upstream port of \bt_p{connection}.
73
74 @bt_pre_not_null{connection}
75 */
76 extern const bt_port_input *bt_connection_borrow_downstream_port_const(
77 const bt_connection *connection) __BT_NOEXCEPT;
78
79 /*!
80 @brief
81 Borrows the downstream \bt_oport of the connection
82 \bt_p{connection}.
83
84 @param[in] connection
85 Connection of which to borrow the downstream port.
86
87 @returns
88 \em Borrowed reference of the downstream port of \bt_p{connection}.
89
90 @bt_pre_not_null{connection}
91 */
92 extern const bt_port_output *bt_connection_borrow_upstream_port_const(
93 const bt_connection *connection) __BT_NOEXCEPT;
94
95 /*! @} */
96
97 /*!
98 @name Reference count
99 @{
100 */
101
102 /*!
103 @brief
104 Increments the \ref api-fund-shared-object "reference count" of
105 the connection \bt_p{connection}.
106
107 @param[in] connection
108 @parblock
109 Connection of which to increment the reference count.
110
111 Can be \c NULL.
112 @endparblock
113
114 @sa bt_connection_put_ref() &mdash;
115 Decrements the reference count of a connection.
116 */
117 extern void bt_connection_get_ref(const bt_connection *connection)
118 __BT_NOEXCEPT;
119
120 /*!
121 @brief
122 Decrements the \ref api-fund-shared-object "reference count" of
123 the connection \bt_p{connection}.
124
125 @param[in] connection
126 @parblock
127 Connection of which to decrement the reference count.
128
129 Can be \c NULL.
130 @endparblock
131
132 @sa bt_connection_get_ref() &mdash;
133 Increments the reference count of a connection.
134 */
135 extern void bt_connection_put_ref(const bt_connection *connection)
136 __BT_NOEXCEPT;
137
138 /*!
139 @brief
140 Decrements the reference count of the connection
141 \bt_p{_connection}, and then sets \bt_p{_connection} to \c NULL.
142
143 @param _connection
144 @parblock
145 Connection of which to decrement the reference count.
146
147 Can contain \c NULL.
148 @endparblock
149
150 @bt_pre_assign_expr{_connection}
151 */
152 #define BT_CONNECTION_PUT_REF_AND_RESET(_connection) \
153 do { \
154 bt_connection_put_ref(_connection); \
155 (_connection) = NULL; \
156 } while (0)
157
158 /*!
159 @brief
160 Decrements the reference count of the connection \bt_p{_dst}, sets
161 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
162
163 This macro effectively moves a connection reference from the expression
164 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
165 \bt_p{_dst} reference.
166
167 @param _dst
168 @parblock
169 Destination expression.
170
171 Can contain \c NULL.
172 @endparblock
173 @param _src
174 @parblock
175 Source expression.
176
177 Can contain \c NULL.
178 @endparblock
179
180 @bt_pre_assign_expr{_dst}
181 @bt_pre_assign_expr{_src}
182 */
183 #define BT_CONNECTION_MOVE_REF(_dst, _src) \
184 do { \
185 bt_connection_put_ref(_dst); \
186 (_dst) = (_src); \
187 (_src) = NULL; \
188 } while (0)
189
190 /*! @} */
191
192 /*! @} */
193
194 #ifdef __cplusplus
195 }
196 #endif
197
198 #endif /* BABELTRACE2_GRAPH_CONNECTION_H */
This page took 0.035645 seconds and 4 git commands to generate.