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