From 19dd0390beaf277efc7a2c319ff48bff46c097d6 Mon Sep 17 00:00:00 2001 From: Simon Marchi Date: Thu, 23 May 2024 16:23:06 -0400 Subject: [PATCH] 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 Reviewed-on: https://review.lttng.org/c/babeltrace/+/9972 Reviewed-by: Philippe Proulx Tested-by: jenkins --- doc/api/libbabeltrace2/Doxyfile.in | 1 + include/babeltrace2/trace-ir/trace.h | 135 +++++++++++++++++++++++++-- src/lib/assert-cond.h | 7 ++ src/lib/lib-logging.c | 10 +- src/lib/trace-ir/trace.c | 34 ++++++- src/lib/trace-ir/trace.h | 18 ++-- 6 files changed, 184 insertions(+), 21 deletions(-) diff --git a/doc/api/libbabeltrace2/Doxyfile.in b/doc/api/libbabeltrace2/Doxyfile.in index 638c0e3c..293ed439 100644 --- 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 954a4387..33c05f8c 100644 --- a/include/babeltrace2/trace-ir/trace.h +++ b/include/babeltrace2/trace-ir/trace.h @@ -86,18 +86,40 @@ A trace has the following properties:
- \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:
- UUID - of the trace. - - The trace's UUID uniquely identifies the trace. - - Use bt_trace_set_uuid() and bt_trace_get_uuid(). +
+
+ \anchor api-tir-trace-prop-uuid + MIP 0: UUID +
+
+ UUID + of the trace. + + The trace's UUID uniquely identifies the trace. + + Use bt_trace_set_uuid() and bt_trace_get_uuid(). +
+ +
+ \anchor api-tir-trace-prop-uid + MIP 1: UID +
+
+ Unique identifier + (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(). +
+
-
\anchor api-tir-trace-prop-env \bt_dt_opt Environment @@ -172,7 +194,10 @@ On success, the returned trace has the following property values: \ref api-tir-trace-prop-name "Name" \em None - \ref api-tir-trace-prop-uuid "UUID" + \bt_mip (MIP) version 0: \ref api-tir-trace-prop-uuid "UUID" + \em None + + MIP 1: \ref api-tir-trace-prop-uid "UID" \em None \ref api-tir-trace-prop-env "Environment" @@ -416,6 +441,16 @@ extern const char *bt_trace_get_name(const bt_trace *trace) __BT_NOEXCEPT; UUID 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 0. + + With MIP 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() — @@ -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 0. + + With MIP 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() — Sets the UUID of a trace. */ extern bt_uuid bt_trace_get_uuid(const bt_trace *trace) __BT_NOEXCEPT; +/*! +@brief + Sets the + unique identifier + (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() — + 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() — + 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 d9c65942..46224ce4 100644 --- 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 541067ea..41bdc66f 100644 --- 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 ef9581ee..f6f973ad 100644 --- 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 4ab18f1b..febf824d 100644 --- 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; -- 2.34.1