include/babeltrace2: add `noexcept` specifier for C++ ≥ 11
[babeltrace.git] / include / babeltrace2 / graph / connection.h
CommitLineData
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
19extern "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
29A <strong><em>connection</em></strong> is a link between an \bt_oport
30and an \bt_iport.
31
32@image html component-zoom.png
33
34A connection is a \ref api-fund-shared-object "shared object": get a new
35reference with bt_connection_get_ref() and put an existing reference with
36bt_connection_put_ref().
37
38The type of a connection is #bt_connection.
39
40Borrow the upstream (output) port and downstream (input) port of a
41connection with bt_connection_borrow_upstream_port_const() and
42bt_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*/
76extern 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*/
92extern 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() &mdash;
115 Decrements the reference count of a connection.
116*/
4c81a2b7
PP
117extern 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() &mdash;
133 Increments the reference count of a connection.
134*/
4c81a2b7
PP
135extern 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
163This 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.048184 seconds and 4 git commands to generate.