@ingroup apiref
@brief Common reference counting management for all Babeltrace objects.
+@code
+#include <babeltrace/ref.h>
+@endcode
+
The macros and functions of this module are everything that is needed
to handle the <strong><em>reference counting</em></strong> of
Babeltrace objects.
-All Babeltrace objects can be shared by multiple owners thanks to
+Any Babeltrace object can be shared by multiple owners thanks to
<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
-counting</a>. A function which returns a Babeltrace object owned
-by another one increments its reference count so that the caller
-becomes an owner too.
+counting</a>.
+
+The Babeltrace C API complies with the following key principles:
+
+1. When you call an API function which accepts a Babeltrace object
+ pointer as a parameter, the API function <strong>borrows the
+ reference</strong> for the <strong>duration of the function</strong>.
+
+ @image html ref-count-user-calls.png
+
+ The API function can also get a new reference if the system needs a
+ more persistent reference, but the ownership is <strong>never
+ transferred</strong> from the caller to the API function.
+
+ In other words, the caller still owns the object after calling any
+ API function: no function "steals" the user's reference (except
+ bt_put()).
+
+2. An API function which \em returns a Babeltrace object pointer to the
+ user returns a <strong>new reference</strong>. The caller becomes an
+ owner of the object.
-When a Babeltrace object is created, its reference count is initialized
-to 1. It is your responsibility to discard the object when you don't
-need it anymore with bt_put().
+ @image html ref-count-api-returns.png
+
+ It is your responsibility to discard the object when you don't
+ need it anymore with bt_put().
+
+ For example, see bt_value_array_get().
+
+3. A Babeltrace object pointer received as a parameter in a user
+ function called back from an API function is a
+ <strong>borrowed</strong>, or <strong>weak reference</strong>: if you
+ need a reference which is more persistent than the duration of the
+ user function, call bt_get() on the pointer.
+
+ @image html ref-count-callback.png
+
+ For example, see bt_value_map_foreach().
The two macros BT_PUT() and BT_MOVE() operate on \em variables rather
than pointer values. You should use BT_PUT() instead of bt_put() when
*/
/**
-@brief Calls bt_put() on variable \p _var, then sets \p _var to \c NULL.
+@brief Calls bt_put() on a variable named \p _var, then
+ sets \p _var to \c NULL.
Using this macro is considered safer than calling bt_put() because it
makes sure that the variable which used to contain a reference to a
Babeltrace object is set to \c NULL so that a future BT_PUT() or
bt_put() call will not cause another, unwanted reference decrementation.
-@param[in,out] _var Variable containing a Babeltrace object's
- address (can be \c NULL).
+@param[in,out] _var Name of a variable containing a
+ Babeltrace object's address (this address
+ can be \c NULL).
-@post <strong>If \c _var is not \c NULL</strong>, its reference
- count is decremented.
-@post \p _var is \c NULL.
+@post <strong>If \p _var does not contain \p NULL</strong>,
+ its reference count is decremented.
+@post \p _var contains \c NULL.
@sa BT_MOVE(): Transfers the ownership of a Babeltrace object from a
variable to another.
} while (0)
/**
-@brief Transfers the ownership of a Babeltrace object from variable
- \p _var_src to variable \p _var_dst.
+@brief Transfers the ownership of a Babeltrace object from a variable
+ named \p _var_src to a variable named \p _var_dst.
This macro implements the following common pattern:
count of this object is 1. The initial call to bt_put() on \p _var_dst
would destroy the object and leave a dangling pointer in \p _var_dst.
-@param[in,out] _var_dst Destination variable, possibly containing the
- address of a Babeltrace object to put first.
-@param[in,out] _var_src Source variable containing the address of a
- Babeltrace object to move.
+@param[in,out] _var_dst Name of the destination variable, containing
+ either the address of a Babeltrace object to
+ put first, or \c NULL.
+@param[in,out] _var_src Name of the source variable, containing
+ either the address of a Babeltrace object to
+ move, or \c NULL.
@pre <strong>If \p _var_dst and \p _var_src contain the same
- value</strong>, this object's reference count is greater than 1.
+ value which is not \c NULL</strong>, this object's reference
+ count is greater than 1.
@post <strong>If \c _var_dst is not \c NULL</strong>, its reference
count is decremented.
-@post \p _var_dst is equal to \p _var_src.
+@post \p _var_dst is equal to the value of \p _var_src \em before
+ you called this macro.
@post \p _var_src is \c NULL.
@sa BT_PUT(): Calls bt_put() on a variable, then sets it to \c NULL.
projects / babeltrace.git / blobdiff