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