lib: add bt_trace_{get,set}_uid

In MIP 1, the trace UID replaces the trace UUID.  A trace UID is an
arbitrary string.  When the trace UID is unset, its value is NULL.

 - Add bt_trace_get_uid and bt_trace_set_uid, to be used with MIP >= 1.

 - Make bt_trace_get_uuid and bt_trace_set_uuid only available with
   MIP == 0.

 - Add BT_ASSERT_PRE_UID_NON_NULL, for use in bt_trace_set_uid.

 - Handle the trace UID in lib-logging.c:format_trace.

 - Free the UID in destroy_trace.

Philippe updated the documentation.

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

diff --git a/doc/api/libbabeltrace2/Doxyfile.in b/doc/api/libbabeltrace2/Doxyfile.in
index 638c0e3c9aca7165568011139c0789e3fcef3a6f..293ed439dc9ee228ffd0b58db74987711229532b 100644 (file)
--- a/doc/api/libbabeltrace2/Doxyfile.in
+++ b/doc/api/libbabeltrace2/Doxyfile.in
@@ -122,6 +122,7 @@ ALIASES                += bt_pre_is_se_msg{1}="@pre \bt_p{\1} is a \link api-msg
 # Aliases: preconditions: MIP version
 ALIASES                += bt_pre_tc_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_fc_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_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: field class object types: singular
 ALIASES                += bt_fc="\link api-tir-fc field class\endlink"

diff --git a/include/babeltrace2/trace-ir/trace.h b/include/babeltrace2/trace-ir/trace.h
index 954a43870e2863317a0108a7822aa02e8550541e..33c05f8c02d63ea7280bf210467b3c676b7d09be 100644 (file)
--- a/include/babeltrace2/trace-ir/trace.h
+++ b/include/babeltrace2/trace-ir/trace.h
@@ -86,18 +86,40 @@ A trace has the following properties:
   </dd>
 
   <dt>
-    \anchor api-tir-trace-prop-uuid
-    \bt_dt_opt UUID
+    \bt_dt_opt Depending on the effective \bt_mip (MIP) version of the
+    trace processing \bt_graph:
   </dt>
   <dd>
-    <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
-    of the trace.
-
-    The trace's UUID uniquely identifies the trace.
-
-    Use bt_trace_set_uuid() and bt_trace_get_uuid().
+    <dl>
+      <dt>
+        \anchor api-tir-trace-prop-uuid
+        MIP&nbsp;0: UUID
+      </dt>
+      <dd>
+        <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
+        of the trace.
+
+        The trace's UUID uniquely identifies the trace.
+
+        Use bt_trace_set_uuid() and bt_trace_get_uuid().
+      </dd>
+
+      <dt>
+        \anchor api-tir-trace-prop-uid
+        MIP&nbsp;1: UID
+      </dt>
+      <dd>
+        <a href="https://en.wikipedia.org/wiki/Unique_identifier">Unique identifier</a>
+        (UID) of the trace.
+
+        The combination of the trace's
+        \link api-tir-trace-prop-name name\endlink and UID
+        uniquely identifies the trace.
+
+        Use bt_trace_set_uid() and bt_trace_get_uid().
+      </dd>
+    </dl>
   </dd>
-
   <dt>
     \anchor api-tir-trace-prop-env
     \bt_dt_opt Environment
@@ -172,7 +194,10 @@ On success, the returned trace has the following property values:
     <td>\ref api-tir-trace-prop-name "Name"
     <td>\em None
   <tr>
-    <td>\ref api-tir-trace-prop-uuid "UUID"
+    <td>\bt_mip (MIP) version&nbsp;0: \ref api-tir-trace-prop-uuid "UUID"
+    <td>\em None
+  <tr>
+    <td>MIP&nbsp;1: \ref api-tir-trace-prop-uid "UID"
     <td>\em None
   <tr>
     <td>\ref api-tir-trace-prop-env "Environment"
@@ -416,6 +441,16 @@ extern const char *bt_trace_get_name(const bt_trace *trace) __BT_NOEXCEPT;
     <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
     of the trace \bt_p{trace} to a copy of \bt_p{uuid}.
 
+@note
+    @parblock
+    This function is only available when the class of \bt_p{trace} was
+    created from a \bt_comp which belongs to a trace processing
+    \bt_graph with the effective \bt_mip (MIP) version&nbsp;0.
+
+    With MIP&nbsp;1, see the
+    \ref api-tir-trace-prop-uid "UID" property.
+    @endparblock
+
 See the \ref api-tir-trace-prop-uuid "UUID" property.
 
 @param[in] trace
@@ -425,6 +460,7 @@ See the \ref api-tir-trace-prop-uuid "UUID" property.
 
 @bt_pre_not_null{trace}
 @bt_pre_hot{trace}
+@bt_pre_trace_with_mip{trace, 0}
 @bt_pre_not_null{uuid}
 
 @sa bt_trace_get_uuid() &mdash;
@@ -432,10 +468,38 @@ See the \ref api-tir-trace-prop-uuid "UUID" property.
 */
 extern void bt_trace_set_uuid(bt_trace *trace, bt_uuid uuid) __BT_NOEXCEPT;
 
+/*!
+@brief
+    Status codes for bt_trace_set_uid().
+*/
+typedef enum bt_trace_set_uid_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_TRACE_SET_UID_STATUS_OK              = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_TRACE_SET_UID_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_trace_set_uid_status;
+
 /*!
 @brief
     Returns the UUID of the trace \bt_p{trace}.
 
+@note
+    @parblock
+    This function is only available when the class of \bt_p{trace} was
+    created from a \bt_comp which belongs to a trace processing
+    \bt_graph with the effective \bt_mip (MIP) version&nbsp;0.
+
+    With MIP&nbsp;1, see the
+    \ref api-tir-trace-prop-uid "UID" property.
+    @endparblock
+
 See the \ref api-tir-trace-prop-uuid "UUID" property.
 
 If \bt_p{trace} has no UUID, this function returns \c NULL.
@@ -452,12 +516,63 @@ If \bt_p{trace} has no UUID, this function returns \c NULL.
     @endparblock
 
 @bt_pre_not_null{trace}
+@bt_pre_trace_with_mip{trace, 0}
 
 @sa bt_trace_set_uuid() &mdash;
     Sets the UUID of a trace.
 */
 extern bt_uuid bt_trace_get_uuid(const bt_trace *trace) __BT_NOEXCEPT;
 
+/*!
+@brief
+    Sets the
+    <a href="https://en.wikipedia.org/wiki/Unique_identifier">unique identifier</a>
+    (UID) of \bt_p{trace} to a copy of \bt_p{uid}.
+
+See the \ref api-tir-trace-prop-uid "UID" property.
+
+@param[in] trace
+    Trace of which to set the UID to \bt_p{uid}.
+@param[in] uid
+    New UID of \bt_p{trace} (copied).
+
+@bt_pre_not_null{trace}
+@bt_pre_hot{trace}
+@bt_pre_trace_with_mip{trace, 1}
+@bt_pre_not_null{uid}
+
+@sa bt_trace_get_uid() &mdash;
+    Returns the UID of a trace.
+*/
+extern bt_trace_set_uid_status bt_trace_set_uid(bt_trace *trace, const char *uid);
+
+/*!
+@brief
+    Returns the UID of the trace \bt_p{trace}.
+
+See the \ref api-tir-trace-prop-uid "UID" property.
+
+If \bt_p{trace} has no UID, this function returns \c NULL.
+
+@param[in] trace
+    Trace of which to get the UID.
+
+@returns
+    @parblock
+    UID of \bt_p{trace}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{trace}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{trace}
+@bt_pre_trace_with_mip{trace, 1}
+
+@sa bt_trace_set_uid() &mdash;
+    Sets the UID of a trace.
+*/
+extern const char *bt_trace_get_uid(const bt_trace *trace);
+
 /*!
 @brief
     Status codes for bt_trace_set_name().

diff --git a/src/lib/assert-cond.h b/src/lib/assert-cond.h
index d9c65942b6392a33c4984c4421744246201f6abd..46224ce4e1d6359e0ee1c76746948e5984a443f4 100644 (file)
--- a/src/lib/assert-cond.h
+++ b/src/lib/assert-cond.h
@@ -1356,6 +1356,13 @@
        BT_ASSERT_PRE_DEV_NON_NULL(_BT_ASSERT_PRE_UUID_ID, (_uuid),     \
                _BT_ASSERT_PRE_UUID_NAME)
 
+#define _BT_ASSERT_PRE_UID_NAME        "Unique identifier"
+#define _BT_ASSERT_PRE_UID_ID  "uid"
+
+#define BT_ASSERT_PRE_UID_NON_NULL(_uid)                               \
+       BT_ASSERT_PRE_NON_NULL(_BT_ASSERT_PRE_UID_ID, (_uid),           \
+               _BT_ASSERT_PRE_UID_NAME)
+
 #define _BT_ASSERT_PRE_KEY_NAME        "Key"
 #define _BT_ASSERT_PRE_KEY_ID  "key"
 

diff --git a/src/lib/lib-logging.c b/src/lib/lib-logging.c
index 541067ea16f27cf8a2532b6e1ae6f398d0d5aa74..41bdc66f66d44a8686394eab785d6e44e9999257 100644 (file)
--- a/src/lib/lib-logging.c
+++ b/src/lib/lib-logging.c
@@ -566,8 +566,14 @@ static inline void format_trace(char **buf_ch, bool extended,
                return;
        }
 
-       if (trace->uuid.value) {
-               BUF_APPEND_UUID(trace->uuid.value);
+       if (trace->class->mip_version >= 1) {
+               if (trace->uid_or_uuid.uid) {
+                       BUF_APPEND(", %suid=\"%s\"", PRFIELD(trace->uid_or_uuid.uid));
+               }
+       } else {
+               if (trace->uid_or_uuid.uuid.value) {
+                       BUF_APPEND_UUID(trace->uid_or_uuid.uuid.value);
+               }
        }
 
        BUF_APPEND(", %sis-frozen=%d", PRFIELD(trace->frozen));

diff --git a/src/lib/trace-ir/trace.c b/src/lib/trace-ir/trace.c
index ef9581ee0e6d01f175eed5de0d45b01f6698ed48..f6f973ad7e96c4de3010136247f5bf097815bf2e 100644 (file)
--- a/src/lib/trace-ir/trace.c
+++ b/src/lib/trace-ir/trace.c
@@ -107,6 +107,11 @@ void destroy_trace(struct bt_object *obj)
 
        g_free(trace->name);
 
+       if (trace->class->mip_version >= 1) {
+               g_free(trace->uid_or_uuid.uid);
+               trace->uid_or_uuid.uid = NULL;
+       }
+
        if (trace->environment) {
                BT_LOGD_STR("Destroying environment attributes.");
                bt_attributes_destroy(trace->environment);
@@ -216,7 +221,16 @@ BT_EXPORT
 bt_uuid bt_trace_get_uuid(const struct bt_trace *trace)
 {
        BT_ASSERT_PRE_DEV_TRACE_NON_NULL(trace);
-       return trace->uuid.value;
+       BT_ASSERT_PRE_TC_MIP_VERSION_EQ(trace->class, 0);
+       return trace->uid_or_uuid.uuid.value;
+}
+
+BT_EXPORT
+const char *bt_trace_get_uid(const bt_trace *trace)
+{
+       BT_ASSERT_PRE_DEV_TRACE_NON_NULL(trace);
+       BT_ASSERT_PRE_TC_MIP_VERSION_GE(trace->class, 1);
+       return trace->uid_or_uuid.uid;
 }
 
 BT_EXPORT
@@ -225,11 +239,25 @@ void bt_trace_set_uuid(struct bt_trace *trace, bt_uuid uuid)
        BT_ASSERT_PRE_TRACE_NON_NULL(trace);
        BT_ASSERT_PRE_UUID_NON_NULL(uuid);
        BT_ASSERT_PRE_DEV_TRACE_HOT(trace);
-       bt_uuid_copy(trace->uuid.uuid, uuid);
-       trace->uuid.value = trace->uuid.uuid;
+       BT_ASSERT_PRE_TC_MIP_VERSION_EQ(trace->class, 0);
+       bt_uuid_copy(trace->uid_or_uuid.uuid.uuid, uuid);
+       trace->uid_or_uuid.uuid.value = trace->uid_or_uuid.uuid.uuid;
        BT_LIB_LOGD("Set trace's UUID: %!+t", trace);
 }
 
+BT_EXPORT
+enum bt_trace_set_uid_status bt_trace_set_uid(bt_trace *trace, const char *uid)
+{
+       BT_ASSERT_PRE_TRACE_NON_NULL(trace);
+       BT_ASSERT_PRE_DEV_TRACE_HOT(trace);
+       BT_ASSERT_PRE_TC_MIP_VERSION_GE(trace->class, 1);
+       BT_ASSERT_PRE_UID_NON_NULL(uid);
+       g_free(trace->uid_or_uuid.uid);
+       trace->uid_or_uuid.uid = g_strdup(uid);
+       BT_LIB_LOGD("Set trace's UID: %!+t", trace);
+       return BT_FUNC_STATUS_OK;
+}
+
 static
 bool trace_has_environment_entry(const struct bt_trace *trace, const char *name)
 {

diff --git a/src/lib/trace-ir/trace.h b/src/lib/trace-ir/trace.h
index 4ab18f1ba4f14cbd65bad46b3e111365f6ec8d6c..febf824d0696cd04219f021eb487f8ce84fbed88 100644 (file)
--- a/src/lib/trace-ir/trace.h
+++ b/src/lib/trace-ir/trace.h
@@ -33,12 +33,18 @@ struct bt_trace {
 
        gchar *name;
 
-       struct {
-               bt_uuid_t uuid;
-
-               /* NULL or `uuid` above */
-               bt_uuid value;
-       } uuid;
+       union {
+               /* Used for MIP == 0 */
+               struct {
+                       bt_uuid_t uuid;
+
+                       /* NULL or `uuid` above */
+                       bt_uuid value;
+               } uuid;
+
+               /* Used for MIP >= 1 */
+               gchar *uid;
+       } uid_or_uuid;
 
        struct bt_value *environment;