lib: Reset libbabeltrace2 to SONANE 0
[babeltrace.git] / include / babeltrace / ctf-writer / object.h
1 #ifndef BABELTRACE_CTF_WRITER_OBJECT_H
2 #define BABELTRACE_CTF_WRITER_OBJECT_H
3
4 /*
5 * Copyright (c) 2015 EfficiOS Inc. and Linux Foundation
6 * Copyright (c) 2015 Philippe Proulx <pproulx@efficios.com>
7 * Copyright (c) 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
8 *
9 * Permission is hereby granted, free of charge, to any person obtaining a copy
10 * of this software and associated documentation files (the "Software"), to deal
11 * in the Software without restriction, including without limitation the rights
12 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13 * copies of the Software, and to permit persons to whom the Software is
14 * furnished to do so, subject to the following conditions:
15 *
16 * The above copyright notice and this permission notice shall be included in
17 * all copies or substantial portions of the Software.
18 *
19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
25 * SOFTWARE.
26 */
27
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31
32 /**
33 @defgroup refs Reference counting management
34 @ingroup apiref
35 @brief Common reference counting management for all Babeltrace objects.
36
37 @code
38 #include <babeltrace/ctf-writer/object.h>
39 @endcode
40
41 The macros and functions of this module are everything that is needed
42 to handle the <strong><em>reference counting</em></strong> of
43 Babeltrace objects.
44
45 Any Babeltrace object can be shared by multiple owners thanks to
46 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
47 counting</a>.
48
49 The Babeltrace C API complies with the following key principles:
50
51 1. When you call an API function which accepts a Babeltrace object
52 pointer as a parameter, the API function <strong>borrows the
53 reference</strong> for the <strong>duration of the function</strong>.
54
55 @image html ref-count-user-calls.png
56
57 The API function can also get a new reference if the system needs a
58 more persistent reference, but the ownership is <strong>never
59 transferred</strong> from the caller to the API function.
60
61 In other words, the caller still owns the object after calling any
62 API function: no function "steals" the user's reference (except
63 bt_ctf_object_put_ref()).
64
65 2. An API function which \em returns a Babeltrace object pointer to the
66 user returns a <strong>new reference</strong>. The caller becomes an
67 owner of the object.
68
69 @image html ref-count-api-returns.png
70
71 It is your responsibility to discard the object when you don't
72 need it anymore with bt_ctf_object_put_ref().
73
74 For example, see bt_ctf_value_array_get().
75
76 3. A Babeltrace object pointer received as a parameter in a user
77 function called back from an API function is a
78 <strong>borrowed</strong>, or <strong>weak reference</strong>: if you
79 need a reference which is more persistent than the duration of the
80 user function, call bt_ctf_object_get_ref() on the pointer.
81
82 @image html ref-count-callback.png
83
84 For example, see bt_ctf_value_map_foreach_entry().
85
86 The two macros BT_CTF_OBJECT_PUT_REF_AND_RESET() and BT_CTF_OBJECT_MOVE_REF() operate on \em variables rather
87 than pointer values. You should use BT_CTF_OBJECT_PUT_REF_AND_RESET() instead of bt_ctf_object_put_ref() when
88 possible to avoid "double puts". For the same reason, you should use use
89 BT_CTF_OBJECT_MOVE_REF() instead of performing manual reference moves between
90 variables.
91
92 @file
93 @brief Reference counting management macros and functions.
94 @sa refs
95
96 @addtogroup refs
97 @{
98 */
99
100 /**
101 @brief Calls bt_ctf_object_put_ref() on a variable named \p _var, then
102 sets \p _var to \c NULL.
103
104 Using this macro is considered safer than calling bt_ctf_object_put_ref() because it
105 makes sure that the variable which used to contain a reference to a
106 Babeltrace object is set to \c NULL so that a future BT_CTF_OBJECT_PUT_REF_AND_RESET() or
107 bt_ctf_object_put_ref() call will not cause another, unwanted reference decrementation.
108
109 @param[in,out] _var Name of a variable containing a
110 Babeltrace object's address (this address
111 can be \c NULL).
112
113 @post <strong>If \p _var does not contain \p NULL</strong>,
114 its reference count is decremented.
115 @post \p _var contains \c NULL.
116
117 @sa BT_CTF_OBJECT_MOVE_REF(): Transfers the ownership of a Babeltrace object from a
118 variable to another.
119 */
120 #define BT_CTF_OBJECT_PUT_REF_AND_RESET(_var) \
121 do { \
122 bt_ctf_object_put_ref(_var); \
123 (_var) = NULL; \
124 } while (0)
125
126 /**
127 @brief Transfers the ownership of a Babeltrace object from a variable
128 named \p _var_src to a variable named \p _var_dst.
129
130 This macro implements the following common pattern:
131
132 1. Call bt_ctf_object_put_ref() on \p _var_dst to make sure the previous reference
133 held by \p _var_dst is discarded.
134 2. Assign \p _var_src to \p _var_dst.
135 3. Set \p _var_src to \c NULL to avoid future, unwanted reference
136 decrementation of \p _var_src.
137
138 @warning
139 You must \em not use this macro when both \p _var_dst and
140 \p _var_src contain the same Babeltrace object address and the reference
141 count of this object is 1. The initial call to bt_ctf_object_put_ref() on \p _var_dst
142 would destroy the object and leave a dangling pointer in \p _var_dst.
143
144 @param[in,out] _var_dst Name of the destination variable, containing
145 either the address of a Babeltrace object to
146 put first, or \c NULL.
147 @param[in,out] _var_src Name of the source variable, containing
148 either the address of a Babeltrace object to
149 move, or \c NULL.
150
151 @pre <strong>If \p _var_dst and \p _var_src contain the same
152 value which is not \c NULL</strong>, this object's reference
153 count is greater than 1.
154 @post <strong>If \c _var_dst is not \c NULL</strong>, its reference
155 count is decremented.
156 @post \p _var_dst is equal to the value of \p _var_src \em before
157 you called this macro.
158 @post \p _var_src is \c NULL.
159
160 @sa BT_CTF_OBJECT_PUT_REF_AND_RESET(): Calls bt_ctf_object_put_ref() on a variable, then sets it to \c NULL.
161 */
162 #define BT_CTF_OBJECT_MOVE_REF(_var_dst, _var_src) \
163 do { \
164 bt_ctf_object_put_ref(_var_dst); \
165 (_var_dst) = (_var_src); \
166 (_var_src) = NULL; \
167 } while (0)
168
169 /**
170 @brief Increments the reference count of the Babeltrace object \p obj.
171
172 @param[in] obj Babeltrace object of which to get a new reference
173 (can be \c NULL).
174 @returns \p obj
175
176 @post <strong>If \c obj is not \c NULL</strong>, its reference
177 count is incremented.
178
179 @sa bt_ctf_object_put_ref(): Decrements the reference count of a Babeltrace object.
180 */
181 void *bt_ctf_object_get_ref(void *obj);
182
183 /**
184 @brief Decrements the reference count of the Babeltrace object
185 \p obj.
186
187 When the object's reference count reaches 0, the object can no longer
188 be accessed and is considered \em destroyed.
189
190 @remarks
191 You should use the BT_CTF_OBJECT_PUT_REF_AND_RESET() macro instead of calling bt_ctf_object_put_ref() since the
192 former is generally safer.
193
194 @param[in] obj Babeltrace object of which to drop a reference
195 (can be \c NULL).
196
197 @post <strong>If \c obj is not \c NULL</strong>, its reference
198 count is decremented.
199
200 @sa BT_CTF_OBJECT_PUT_REF_AND_RESET(): Calls bt_ctf_object_put_ref() on a variable, then sets it to \c NULL.
201 @sa BT_CTF_OBJECT_MOVE_REF(): Transfers the ownership of a Babeltrace object from a
202 variable to another.
203 @sa bt_ctf_object_get_ref(): Increments the reference count of a Babeltrace object.
204 */
205 void bt_ctf_object_put_ref(void *obj);
206
207 /**
208 @}
209 */
210
211 #ifdef __cplusplus
212 }
213 #endif
214
215 #endif /* BABELTRACE_CTF_WRITER_OBJECT_H */
This page took 0.034455 seconds and 4 git commands to generate.