Initial implementation of the debuginfo API

[babeltrace.git] / include / babeltrace / ref.h

diff --git a/include/babeltrace/ref.h b/include/babeltrace/ref.h
index a667f6f28330023cca59fdc7d7b7a6eb0a51011b..63cf2f0208cbb3e29bd0e3fec3fcb981e338976c 100644 (file)
--- a/include/babeltrace/ref.h
+++ b/include/babeltrace/ref.h
@@ -27,6 +27,10 @@
  * SOFTWARE.
  */
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /*
  * BT_PUT: calls bt_put() with a variable, then sets this variable to NULL.
  *
@@ -36,9 +40,9 @@
  * to NULL after putting the object it points to. Since this is so
  * common, the BT_PUT() macro can be used to do just that.
  *
- * It is safe to call this function with a NULL object.
+ * It is safe to call this function with a variable containing NULL.
  *
- * @param obj Babeltrace object.
+ * @param obj Variable pointing to a Babeltrace object.
  */
 #define BT_PUT(_obj)           \
        do {                    \
@@ -53,10 +57,15 @@
  * then sets _src to NULL, effectively moving the ownership of an
  * object from one variable to the other.
  *
- * @param obj Babeltrace object.
+ * Before assigning _src to _dst, it puts _dst. Therefore it is not safe to
+ * call this function with an uninitialized value of _dst.
+ *
+ * @param _dst Destination variable pointing to a Babeltrace object.
+ * @param _src Source variable pointing to a Babeltrace object.
  */
 #define BT_MOVE(_dst, _src)    \
        do {                    \
+               bt_put(_dst);   \
                (_dst) = (_src);\
                (_src) = NULL;  \
        } while (0)
@@ -71,8 +80,10 @@
  * It is safe to call this function with a NULL object.
  *
  * @param obj Babeltrace object.
+ *
+ * Returns obj.
  */
-void bt_get(void *obj);
+void *bt_get(void *obj);
 
 /*
  * bt_put: decrements the reference count of a Babeltrace object.
@@ -81,7 +92,7 @@ void bt_get(void *obj);
  * bt_put() to release the initial reference done at creation) have to be
  * performed to destroy a Babeltrace object.
  *
- * The object is feed when its reference count is decremented to 0 by a call to
+ * The object is freed when its reference count is decremented to 0 by a call to
  * bt_put().
  *
  * It is safe to call this function with a NULL object.
@@ -90,4 +101,8 @@ void bt_get(void *obj);
  */
 void bt_put(void *obj);
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif /* BABELTRACE_REF_H */