Commit | Line | Data |
---|---|---|
43c59509 | 1 | /* |
0235b0db | 2 | * SPDX-License-Identifier: MIT |
43c59509 | 3 | * |
0235b0db | 4 | * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation |
43c59509 PP |
5 | */ |
6 | ||
0235b0db MJ |
7 | #ifndef BABELTRACE2_GRAPH_CONNECTION_H |
8 | #define BABELTRACE2_GRAPH_CONNECTION_H | |
9 | ||
f38da6ca SM |
10 | /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */ |
11 | ||
43c59509 PP |
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( | |
4c81a2b7 | 77 | const bt_connection *connection) __BT_NOEXCEPT; |
43c59509 PP |
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( | |
4c81a2b7 | 93 | const bt_connection *connection) __BT_NOEXCEPT; |
43c59509 PP |
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() — | |
115 | Decrements the reference count of a connection. | |
116 | */ | |
4c81a2b7 PP |
117 | extern void bt_connection_get_ref(const bt_connection *connection) |
118 | __BT_NOEXCEPT; | |
43c59509 PP |
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() — | |
133 | Increments the reference count of a connection. | |
134 | */ | |
4c81a2b7 PP |
135 | extern void bt_connection_put_ref(const bt_connection *connection) |
136 | __BT_NOEXCEPT; | |
43c59509 PP |
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 */ |