Document libbabeltrace2's C API

[babeltrace.git] / src / lib / trace-ir / trace.c

diff --git a/src/lib/trace-ir/trace.c b/src/lib/trace-ir/trace.c
index e884c72a29ed0887bfe1da7880b02863684457dd..688a113eb77f41862856c9403a7383455e54ba9b 100644 (file)
--- a/src/lib/trace-ir/trace.c
+++ b/src/lib/trace-ir/trace.c
@@ -25,14 +25,13 @@
 #include "lib/logging.h"
 
 #include "lib/assert-pre.h"
+#include "lib/assert-post.h"
 #include <babeltrace2/trace-ir/trace.h>
-#include <babeltrace2/trace-ir/trace-const.h>
 #include <babeltrace2/trace-ir/event-class.h>
 #include "ctf-writer/functor.h"
 #include "ctf-writer/clock.h"
 #include "compat/compiler.h"
 #include <babeltrace2/value.h>
-#include <babeltrace2/value-const.h>
 #include "lib/value.h"
 #include <babeltrace2/types.h>
 #include "compat/endian.h"
@@ -41,6 +40,7 @@
 #include <inttypes.h>
 #include <stdint.h>
 #include <string.h>
+#include <stdbool.h>
 #include <stdlib.h>
 
 #include "attributes.h"
@@ -55,6 +55,7 @@
 #include "trace-class.h"
 #include "trace.h"
 #include "utils.h"
+#include "lib/value.h"
 #include "lib/func-status.h"
 
 struct bt_trace_destruction_listener_elem {
@@ -71,6 +72,7 @@ void destroy_trace(struct bt_object *obj)
        struct bt_trace *trace = (void *) obj;
 
        BT_LIB_LOGD("Destroying trace object: %!+t", trace);
+       BT_OBJECT_PUT_REF_AND_RESET(trace->user_attributes);
 
        /*
         * Call destruction listener functions so that everything else
@@ -78,6 +80,8 @@ void destroy_trace(struct bt_object *obj)
         */
        if (trace->destruction_listeners) {
                uint64_t i;
+               const struct bt_error *saved_error;
+
                BT_LIB_LOGD("Calling trace destruction listener(s): %!+t", trace);
 
                /*
@@ -92,6 +96,8 @@ void destroy_trace(struct bt_object *obj)
                */
                trace->base.ref_count++;
 
+               saved_error = bt_current_thread_take_error();
+
                /* Call all the trace destruction listeners */
                for (i = 0; i < trace->destruction_listeners->len; i++) {
                        struct bt_trace_destruction_listener_elem elem =
@@ -100,16 +106,21 @@ void destroy_trace(struct bt_object *obj)
 
                        if (elem.func) {
                                elem.func(trace, elem.data);
+                               BT_ASSERT_POST_NO_ERROR();
                        }
 
                        /*
                         * The destruction listener should not have kept a
                         * reference to the trace.
                         */
-                       BT_ASSERT_PRE(trace->base.ref_count == 1, "Destruction listener kept a reference to the trace being destroyed: %![trace-]+t", trace);
+                       BT_ASSERT_POST(trace->base.ref_count == 1, "Destruction listener kept a reference to the trace being destroyed: %![trace-]+t", trace);
                }
                g_array_free(trace->destruction_listeners, TRUE);
                trace->destruction_listeners = NULL;
+
+               if (saved_error) {
+                       BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET(saved_error);
+               }
        }
 
        if (trace->name.str) {
@@ -145,6 +156,8 @@ struct bt_trace *bt_trace_create(struct bt_trace_class *tc)
 {
        struct bt_trace *trace = NULL;
 
+       BT_ASSERT_PRE_NO_ERROR();
+
        BT_LIB_LOGD("Creating trace object: %![tc-]+T", tc);
        trace = g_new0(struct bt_trace, 1);
        if (!trace) {
@@ -153,6 +166,13 @@ struct bt_trace *bt_trace_create(struct bt_trace_class *tc)
        }
 
        bt_object_init_shared(&trace->base, destroy_trace);
+       trace->user_attributes = bt_value_map_create();
+       if (!trace->user_attributes) {
+               BT_LIB_LOGE_APPEND_CAUSE(
+                       "Failed to create a map value object.");
+               goto error;
+       }
+
        trace->streams = g_ptr_array_new_with_free_func(
                (GDestroyNotify) bt_object_try_spec_release);
        if (!trace->streams) {
@@ -187,7 +207,7 @@ struct bt_trace *bt_trace_create(struct bt_trace_class *tc)
        }
 
        trace->class = tc;
-       bt_object_get_no_null_check(trace->class);
+       bt_object_get_ref_no_null_check(trace->class);
        BT_LIB_LOGD("Created trace object: %!+t", trace);
        goto end;
 
@@ -207,6 +227,7 @@ const char *bt_trace_get_name(const struct bt_trace *trace)
 enum bt_trace_set_name_status bt_trace_set_name(struct bt_trace *trace,
                const char *name)
 {
+       BT_ASSERT_PRE_NO_ERROR();
        BT_ASSERT_PRE_NON_NULL(trace, "Trace");
        BT_ASSERT_PRE_NON_NULL(name, "Name");
        BT_ASSERT_PRE_DEV_TRACE_HOT(trace);
@@ -232,14 +253,13 @@ void bt_trace_set_uuid(struct bt_trace *trace, bt_uuid uuid)
        BT_LIB_LOGD("Set trace's UUID: %!+t", trace);
 }
 
-BT_ASSERT_FUNC
 static
 bool trace_has_environment_entry(const struct bt_trace *trace, const char *name)
 {
        BT_ASSERT(trace);
 
        return bt_attributes_borrow_field_value_by_name(
-               trace->environment, name) != NULL;
+               trace->environment, name);
 }
 
 static
@@ -278,9 +298,12 @@ bt_trace_set_environment_entry_string(
 {
        int ret;
        struct bt_value *value_obj;
+
+       BT_ASSERT_PRE_NO_ERROR();
        BT_ASSERT_PRE_NON_NULL(trace, "Trace");
        BT_ASSERT_PRE_NON_NULL(name, "Name");
        BT_ASSERT_PRE_NON_NULL(value, "Value");
+
        value_obj = bt_value_string_create_init(value);
        if (!value_obj) {
                BT_LIB_LOGE_APPEND_CAUSE(
@@ -303,8 +326,11 @@ bt_trace_set_environment_entry_integer(
 {
        int ret;
        struct bt_value *value_obj;
+
+       BT_ASSERT_PRE_NO_ERROR();
        BT_ASSERT_PRE_NON_NULL(trace, "Trace");
        BT_ASSERT_PRE_NON_NULL(name, "Name");
+
        value_obj = bt_value_integer_signed_create_init(value);
        if (!value_obj) {
                BT_LIB_LOGE_APPEND_CAUSE(
@@ -323,12 +349,8 @@ end:
 
 uint64_t bt_trace_get_environment_entry_count(const struct bt_trace *trace)
 {
-       int64_t ret;
-
        BT_ASSERT_PRE_DEV_NON_NULL(trace, "Trace");
-       ret = bt_attributes_get_count(trace->environment);
-       BT_ASSERT(ret >= 0);
-       return (uint64_t) ret;
+       return bt_attributes_get_count(trace->environment);
 }
 
 void bt_trace_borrow_environment_entry_by_index_const(
@@ -406,7 +428,7 @@ const struct bt_stream *bt_trace_borrow_stream_by_id_const(
 enum bt_trace_add_listener_status bt_trace_add_destruction_listener(
                const struct bt_trace *c_trace,
                bt_trace_destruction_listener_func listener,
-               void *data, uint64_t *listener_id)
+               void *data, bt_listener_id *listener_id)
 {
        struct bt_trace *trace = (void *) c_trace;
        uint64_t i;
@@ -415,6 +437,7 @@ enum bt_trace_add_listener_status bt_trace_add_destruction_listener(
                .data = data,
        };
 
+       BT_ASSERT_PRE_NO_ERROR();
        BT_ASSERT_PRE_NON_NULL(trace, "Trace");
        BT_ASSERT_PRE_NON_NULL(listener, "Listener");
 
@@ -450,15 +473,16 @@ bool has_listener_id(const struct bt_trace *trace, uint64_t listener_id)
        BT_ASSERT(listener_id < trace->destruction_listeners->len);
        return (&g_array_index(trace->destruction_listeners,
                        struct bt_trace_destruction_listener_elem,
-                       listener_id))->func != NULL;
+                       listener_id))->func;
 }
 
 enum bt_trace_remove_listener_status bt_trace_remove_destruction_listener(
-               const struct bt_trace *c_trace, uint64_t listener_id)
+               const struct bt_trace *c_trace, bt_listener_id listener_id)
 {
        struct bt_trace *trace = (void *) c_trace;
        struct bt_trace_destruction_listener_elem *elem;
 
+       BT_ASSERT_PRE_NO_ERROR();
        BT_ASSERT_PRE_NON_NULL(trace, "Trace");
        BT_ASSERT_PRE(has_listener_id(trace, listener_id),
                "Trace has no such trace destruction listener ID: "
@@ -482,6 +506,9 @@ void _bt_trace_freeze(const struct bt_trace *trace)
        BT_ASSERT(trace);
        BT_LIB_LOGD("Freezing trace's class: %!+T", trace->class);
        bt_trace_class_freeze(trace->class);
+       BT_LIB_LOGD("Freezing trace's user attributes: %!+v",
+               trace->user_attributes);
+       bt_value_freeze(trace->user_attributes);
        BT_LIB_LOGD("Freezing trace: %!+t", trace);
        ((struct bt_trace *) trace)->frozen = true;
 }
@@ -535,6 +562,32 @@ const struct bt_trace_class *bt_trace_borrow_class_const(
        return bt_trace_borrow_class((void *) trace);
 }
 
+const struct bt_value *bt_trace_borrow_user_attributes_const(
+               const struct bt_trace *trace)
+{
+       BT_ASSERT_PRE_DEV_NON_NULL(trace, "Trace");
+       return trace->user_attributes;
+}
+
+struct bt_value *bt_trace_borrow_user_attributes(struct bt_trace *trace)
+{
+       return (void *) bt_trace_borrow_user_attributes_const((void *) trace);
+}
+
+void bt_trace_set_user_attributes(
+               struct bt_trace *trace,
+               const struct bt_value *user_attributes)
+{
+       BT_ASSERT_PRE_NON_NULL(trace, "Trace");
+       BT_ASSERT_PRE_NON_NULL(user_attributes, "User attributes");
+       BT_ASSERT_PRE(user_attributes->type == BT_VALUE_TYPE_MAP,
+               "User attributes object is not a map value object.");
+       BT_ASSERT_PRE_DEV_TRACE_HOT(trace);
+       bt_object_put_ref_no_null_check(trace->user_attributes);
+       trace->user_attributes = (void *) user_attributes;
+       bt_object_get_ref_no_null_check(trace->user_attributes);
+}
+
 void bt_trace_get_ref(const struct bt_trace *trace)
 {
        bt_object_get_ref(trace);