lib: add namespace property to event classes

Add the namespace property to event classes, with the intent to support
namespace properties on event record classes in CTF2‑SPEC‑2.0 [1].

Copy everything from the existing name property, and rename it to
"namespace."

Both new public functions have a `MIP >= 1` pre-condition check.

Philippe updated the documentation.

[1] https://diamon.org/ctf/CTF2-SPEC-2.0.html

Change-Id: I644446087b6071f2ccc70027b079615f3a33a2a7
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/7381
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/12689

diff --git a/doc/api/libbabeltrace2/Doxyfile.in b/doc/api/libbabeltrace2/Doxyfile.in
index a18353a14769bd8ea5d1da0525653e475e50f96a..5fb8ad29137a8b74627f5ac6108c9b019c8557f0 100644 (file)
--- a/doc/api/libbabeltrace2/Doxyfile.in
+++ b/doc/api/libbabeltrace2/Doxyfile.in
@@ -133,6 +133,7 @@ ALIASES                += bt_pre_field_with_mip{2}="@pre The class of \bt_p{\1}
 ALIASES                += bt_pre_trace_with_mip{2}="@pre The \link api-tir-trace-cls class\endlink of \bt_p{\1} was created from a \bt_comp which belongs to a trace processing \bt_graph with the effective \bt_mip version \2."
 ALIASES                += bt_pre_clock_cls_with_mip{2}="@pre \bt_p{\1} was created from a \bt_comp which belongs to a trace processing \bt_graph with the effective \bt_mip version \2."
 ALIASES                += bt_pre_stream_cls_with_mip{2}="@pre \bt_p{\1} was created from a \bt_trace_cls which was created from a \bt_comp which belongs to a trace processing \bt_graph with the effective \bt_mip version \2."
+ALIASES                += bt_pre_ev_cls_with_mip{2}="@pre The parent \bt_trace_cls of \bt_p{\1} was created from a \bt_comp which belongs to a trace processing \bt_graph with the effective \bt_mip version \2."
 
 # Aliases: field class object types: singular
 ALIASES                += bt_fc="\link api-tir-fc field class\endlink"

diff --git a/include/babeltrace2/trace-ir/event-class.h b/include/babeltrace2/trace-ir/event-class.h
index f4e815d5e6847e4c1ddbecf97bcd89b78f5a9d40..c00ba9aceee99401cebd59607661bc1790d84560 100644 (file)
--- a/include/babeltrace2/trace-ir/event-class.h
+++ b/include/babeltrace2/trace-ir/event-class.h
@@ -99,6 +99,20 @@ An event class has the following properties:
     Get an event class's numeric ID with bt_event_class_get_id().
   </dd>
 
+  <dt>
+    \anchor api-tir-ev-cls-prop-ns
+    \bt_dt_opt Namespace
+    (only available when the parent \bt_trace_cls was created
+    from a \bt_comp which belongs to a trace processing \bt_graph
+    with the effective \bt_mip version&nbsp;1)
+  </dt>
+  <dd>
+    Namespace of the event class.
+
+    Use bt_event_class_set_namespace() and
+    bt_event_class_get_namespace().
+  </dd>
+
   <dt>\anchor api-tir-ev-cls-prop-name \bt_dt_opt Name</dt>
   <dd>
     Name of the event class.
@@ -221,6 +235,9 @@ On success, the returned event class has the following property values:
   <tr>
     <td>\ref api-tir-ev-cls-prop-id "Numeric ID"
     <td>Automatically assigned by \bt_p{stream_class}
+  <tr>
+    <td>\bt_mip version&nbsp;1: \ref api-tir-ev-cls-prop-ns "namespace"
+    <td>\em None
   <tr>
     <td>\ref api-tir-ev-cls-prop-name "Name"
     <td>\em None
@@ -288,6 +305,9 @@ On success, the returned event class has the following property values:
   <tr>
     <td>\ref api-tir-ev-cls-prop-id "Numeric ID"
     <td>\bt_p{id}
+  <tr>
+    <td>\bt_mip version&nbsp;1: \ref api-tir-ev-cls-prop-ns "namespace"
+    <td>\em None
   <tr>
     <td>\ref api-tir-ev-cls-prop-name "Name"
     <td>\em None
@@ -398,6 +418,80 @@ See the \ref api-tir-ev-cls-prop-id "numeric ID" property.
 extern uint64_t bt_event_class_get_id(
                const bt_event_class *event_class) __BT_NOEXCEPT;
 
+/*!
+@brief
+    Status codes for bt_event_class_set_namespace().
+*/
+typedef enum bt_event_class_set_namespace_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_EVENT_CLASS_SET_NAMESPACE_STATUS_OK                  = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_EVENT_CLASS_SET_NAMESPACE_STATUS_MEMORY_ERROR        = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_event_class_set_namespace_status;
+
+/*!
+@brief
+    Sets the namespace of the event class \bt_p{event_class} to
+    a copy of \bt_p{ns}.
+
+See the \ref api-tir-ev-cls-prop-ns "namespace" property.
+
+@param[in] event_class
+    Event class of which to set the namespace to \bt_p{ns}.
+@param[in] name
+    New namespace of \bt_p{event_class} (copied).
+
+@retval #BT_EVENT_CLASS_SET_NAMESPACE_STATUS_OK
+    Success.
+@retval #BT_EVENT_CLASS_SET_NAMESPACE_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{event_class}
+@bt_pre_hot{event_class}
+@bt_pre_ev_cls_with_mip{event_class, 1}
+@bt_pre_not_null{ns}
+
+@sa bt_event_class_get_namespace() &mdash;
+    Returns the namespace of an event class.
+*/
+extern bt_event_class_set_namespace_status bt_event_class_set_namespace(
+               bt_event_class *event_class, const char *ns) __BT_NOEXCEPT;
+
+/*!
+@brief
+    Returns the namespace of the event class \bt_p{event_class}.
+
+See the \ref api-tir-ev-cls-prop-ns "namespace" property.
+
+If \bt_p{event_class} has no namespace, this function returns \c NULL.
+
+@param[in] event_class
+    Event class of which to get the namespace.
+
+@returns
+    @parblock
+    Namespace of \bt_p{event_class}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{event_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{event_class}
+@bt_pre_ev_cls_with_mip{event_class, 1}
+
+@sa bt_event_class_set_namespace() &mdash;
+    Sets the namespace of a event class.
+*/
+extern const char *
+bt_event_class_get_namespace(const bt_event_class *event_class) __BT_NOEXCEPT;
+
 /*!
 @brief
     Status codes for bt_event_class_set_name().

diff --git a/src/lib/assert-cond.h b/src/lib/assert-cond.h
index a666c52a0b7e4f9ea85425b2d5abfe132bea3974..bdeee5d49f1fea71a536df45d15bc28b17da6bed 100644 (file)
--- a/src/lib/assert-cond.h
+++ b/src/lib/assert-cond.h
@@ -9,6 +9,7 @@
 #define BABELTRACE_LIB_ASSERT_COND_H
 
 #include "assert-cond-base.h"
+#include "trace-ir/trace-class.h" /* IWYU pragma: keep */
 
 #include <inttypes.h>
 
@@ -1072,6 +1073,15 @@
                bt_stream_class_borrow_trace_class_inline(_stream_class),       \
                _val)
 
+/*
+ * Asserts that the effective MIP version for `_event_class` is greater than or
+ * equal to `_val`.
+ */
+#define BT_ASSERT_PRE_EC_MIP_VERSION_GE(_event_class, _val)                    \
+       BT_ASSERT_PRE_SC_MIP_VERSION_GE(                                        \
+               bt_event_class_borrow_stream_class_inline(_event_class),        \
+               _val)
+
 /*
  * Asserts that the effective MIP version for `_field_class` is equal to `_val`.
  */

diff --git a/src/lib/lib-logging.c b/src/lib/lib-logging.c
index 3342b73910f96744bd6fd339ab8ed36fe1f02e8f..f87a748f835698f77371c3958fd8c4160f5d43a5 100644 (file)
--- a/src/lib/lib-logging.c
+++ b/src/lib/lib-logging.c
@@ -697,9 +697,12 @@ static inline void format_event_class(char **buf_ch, bool extended,
 
        BUF_APPEND(", %sid=%" PRIu64, PRFIELD(event_class->id));
 
+       if (event_class->ns) {
+               BUF_APPEND(", %snamespace=\"%s\"", PRFIELD(event_class->ns));
+       }
+
        if (event_class->name) {
-               BUF_APPEND(", %sname=\"%s\"",
-                       PRFIELD(event_class->name));
+               BUF_APPEND(", %sname=\"%s\"", PRFIELD(event_class->name));
        }
 
        if (!extended) {

diff --git a/src/lib/trace-ir/event-class.c b/src/lib/trace-ir/event-class.c
index 12bb1120692525fa26be7e97573158befc89c033..48f39fef967114912d34dc409e1e6fb674578343 100644 (file)
--- a/src/lib/trace-ir/event-class.c
+++ b/src/lib/trace-ir/event-class.c
@@ -41,6 +41,7 @@ void destroy_event_class(struct bt_object *obj)
        BT_LIB_LOGD("Destroying event class: %!+E", event_class);
        BT_OBJECT_PUT_REF_AND_RESET(event_class->user_attributes);
 
+       g_free(event_class->ns);
        g_free(event_class->name);
        g_free(event_class->emf_uri);
        BT_LOGD_STR("Putting context field class.");
@@ -164,6 +165,29 @@ struct bt_event_class *bt_event_class_create_with_id(
        return create_event_class_with_id(stream_class, id);
 }
 
+BT_EXPORT
+const char *bt_event_class_get_namespace(const struct bt_event_class *event_class)
+{
+       BT_ASSERT_PRE_DEV_EC_NON_NULL(event_class);
+       BT_ASSERT_PRE_EC_MIP_VERSION_GE(event_class, 1);
+       return event_class->ns;
+}
+
+BT_EXPORT
+enum bt_event_class_set_namespace_status bt_event_class_set_namespace(
+               struct bt_event_class *event_class, const char *ns)
+{
+       BT_ASSERT_PRE_NO_ERROR();
+       BT_ASSERT_PRE_EC_NON_NULL(event_class);
+       BT_ASSERT_PRE_EC_MIP_VERSION_GE(event_class, 1);
+       BT_ASSERT_PRE_NAMESPACE_NON_NULL(ns);
+       BT_ASSERT_PRE_DEV_EVENT_CLASS_HOT(event_class);
+       g_free(event_class->ns);
+       event_class->ns = g_strdup(ns);
+       BT_LIB_LOGD("Set event class's namespace: %!+E", event_class);
+       return BT_FUNC_STATUS_OK;
+}
+
 BT_EXPORT
 const char *bt_event_class_get_name(const struct bt_event_class *event_class)
 {

diff --git a/src/lib/trace-ir/event-class.h b/src/lib/trace-ir/event-class.h
index 5e1d50712158bb16b224b06887139a7c1ae4e648..815a607d8a8ba007e8c0c6b56d70b4b4e6156c08 100644 (file)
--- a/src/lib/trace-ir/event-class.h
+++ b/src/lib/trace-ir/event-class.h
@@ -29,6 +29,7 @@ struct bt_event_class {
        /* Owned by this */
        struct bt_value *user_attributes;
 
+       gchar *ns;
        gchar *name;
 
        uint64_t id;