2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_CTF_WRITER_OBJECT_H
8 #define BABELTRACE2_CTF_WRITER_OBJECT_H
15 @defgroup refs Reference counting management
17 @brief Common reference counting management for all Babeltrace objects.
20 #include <babeltrace2-ctf-writer/object.h>
23 The macros and functions of this module are everything that is needed
24 to handle the <strong><em>reference counting</em></strong> of
27 Any Babeltrace object can be shared by multiple owners thanks to
28 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
31 The Babeltrace C API complies with the following key principles:
33 1. When you call an API function which accepts a Babeltrace object
34 pointer as a parameter, the API function <strong>borrows the
35 reference</strong> for the <strong>duration of the function</strong>.
37 @image html ref-count-user-calls.png
39 The API function can also get a new reference if the system needs a
40 more persistent reference, but the ownership is <strong>never
41 transferred</strong> from the caller to the API function.
43 In other words, the caller still owns the object after calling any
44 API function: no function "steals" the user's reference (except
45 bt_ctf_object_put_ref()).
47 2. An API function which \em returns a Babeltrace object pointer to the
48 user returns a <strong>new reference</strong>. The caller becomes an
51 @image html ref-count-api-returns.png
53 It is your responsibility to discard the object when you don't
54 need it anymore with bt_ctf_object_put_ref().
56 For example, see bt_ctf_value_array_get().
58 3. A Babeltrace object pointer received as a parameter in a user
59 function called back from an API function is a
60 <strong>borrowed</strong>, or <strong>weak reference</strong>: if you
61 need a reference which is more persistent than the duration of the
62 user function, call bt_ctf_object_get_ref() on the pointer.
64 @image html ref-count-callback.png
66 For example, see bt_ctf_value_map_foreach_entry().
68 The two macros BT_CTF_OBJECT_PUT_REF_AND_RESET() and BT_CTF_OBJECT_MOVE_REF() operate on \em variables rather
69 than pointer values. You should use BT_CTF_OBJECT_PUT_REF_AND_RESET() instead of bt_ctf_object_put_ref() when
70 possible to avoid "double puts". For the same reason, you should use use
71 BT_CTF_OBJECT_MOVE_REF() instead of performing manual reference moves between
75 @brief Reference counting management macros and functions.
83 @brief Calls bt_ctf_object_put_ref() on a variable named \p _var, then
84 sets \p _var to \c NULL.
86 Using this macro is considered safer than calling bt_ctf_object_put_ref() because it
87 makes sure that the variable which used to contain a reference to a
88 Babeltrace object is set to \c NULL so that a future BT_CTF_OBJECT_PUT_REF_AND_RESET() or
89 bt_ctf_object_put_ref() call will not cause another, unwanted reference decrementation.
91 @param[in,out] _var Name of a variable containing a
92 Babeltrace object's address (this address
95 @post <strong>If \p _var does not contain \p NULL</strong>,
96 its reference count is decremented.
97 @post \p _var contains \c NULL.
99 @sa BT_CTF_OBJECT_MOVE_REF(): Transfers the ownership of a Babeltrace object from a
102 #define BT_CTF_OBJECT_PUT_REF_AND_RESET(_var) \
104 bt_ctf_object_put_ref(_var); \
109 @brief Transfers the ownership of a Babeltrace object from a variable
110 named \p _var_src to a variable named \p _var_dst.
112 This macro implements the following common pattern:
114 1. Call bt_ctf_object_put_ref() on \p _var_dst to make sure the previous reference
115 held by \p _var_dst is discarded.
116 2. Assign \p _var_src to \p _var_dst.
117 3. Set \p _var_src to \c NULL to avoid future, unwanted reference
118 decrementation of \p _var_src.
121 You must \em not use this macro when both \p _var_dst and
122 \p _var_src contain the same Babeltrace object address and the reference
123 count of this object is 1. The initial call to bt_ctf_object_put_ref() on \p _var_dst
124 would destroy the object and leave a dangling pointer in \p _var_dst.
126 @param[in,out] _var_dst Name of the destination variable, containing
127 either the address of a Babeltrace object to
128 put first, or \c NULL.
129 @param[in,out] _var_src Name of the source variable, containing
130 either the address of a Babeltrace object to
133 @pre <strong>If \p _var_dst and \p _var_src contain the same
134 value which is not \c NULL</strong>, this object's reference
135 count is greater than 1.
136 @post <strong>If \c _var_dst is not \c NULL</strong>, its reference
137 count is decremented.
138 @post \p _var_dst is equal to the value of \p _var_src \em before
139 you called this macro.
140 @post \p _var_src is \c NULL.
142 @sa BT_CTF_OBJECT_PUT_REF_AND_RESET(): Calls bt_ctf_object_put_ref() on a variable, then sets it to \c NULL.
144 #define BT_CTF_OBJECT_MOVE_REF(_var_dst, _var_src) \
146 bt_ctf_object_put_ref(_var_dst); \
147 (_var_dst) = (_var_src); \
152 @brief Increments the reference count of the Babeltrace object \p obj.
154 @param[in] obj Babeltrace object of which to get a new reference
158 @post <strong>If \c obj is not \c NULL</strong>, its reference
159 count is incremented.
161 @sa bt_ctf_object_put_ref(): Decrements the reference count of a Babeltrace object.
163 void *bt_ctf_object_get_ref(void *obj
);
166 @brief Decrements the reference count of the Babeltrace object
169 When the object's reference count reaches 0, the object can no longer
170 be accessed and is considered \em destroyed.
173 You should use the BT_CTF_OBJECT_PUT_REF_AND_RESET() macro instead of calling bt_ctf_object_put_ref() since the
174 former is generally safer.
176 @param[in] obj Babeltrace object of which to drop a reference
179 @post <strong>If \c obj is not \c NULL</strong>, its reference
180 count is decremented.
182 @sa BT_CTF_OBJECT_PUT_REF_AND_RESET(): Calls bt_ctf_object_put_ref() on a variable, then sets it to \c NULL.
183 @sa BT_CTF_OBJECT_MOVE_REF(): Transfers the ownership of a Babeltrace object from a
185 @sa bt_ctf_object_get_ref(): Increments the reference count of a Babeltrace object.
187 void bt_ctf_object_put_ref(void *obj
);
197 #endif /* BABELTRACE2_CTF_WRITER_OBJECT_H */
This page took 0.032954 seconds and 4 git commands to generate.