From 8f351a1579abd902ab9ddd00a5820bdb7207b59a Mon Sep 17 00:00:00 2001 From: Mathieu Desnoyers Date: Wed, 27 Mar 2024 19:09:06 -0400 Subject: [PATCH] lib: add bt_get_greatest_operative_mip_version_with_restriction() This new function works like bt_get_greatest_operative_mip_version(), but has an additional optional MIP version restriction range set. For example, if all the components would support MIP 0 and 1, bt_get_greatest_operative_mip_version() would return 1, while bt_get_greatest_operative_mip_version_with_restriction() with the `mip_version_restriction` parameter only containing [0, 0] would return 0. This new function provides more control over the preferred MIP version to use while avoiding the complexity of exposing a direct "get supported MIP versions" method call. Philippe updated the documentation. Signed-off-by: Mathieu Desnoyers Change-Id: Ic8bbdee6055a0816e398f0f27ac0ca8c45f0b85a Reviewed-on: https://review.lttng.org/c/babeltrace/+/12791 Reviewed-by: Philippe Proulx Tested-by: jenkins CI-Build: Simon Marchi --- .../babeltrace2/graph/component-class-dev.h | 22 ++-- .../graph/component-descriptor-set.h | 6 +- include/babeltrace2/graph/message.h | 117 +++++++++++++++--- include/babeltrace2/logging.h | 5 +- src/lib/graph/mip.c | 37 +++++- 5 files changed, 151 insertions(+), 36 deletions(-) diff --git a/include/babeltrace2/graph/component-class-dev.h b/include/babeltrace2/graph/component-class-dev.h index 7e59f665..94150988 100644 --- a/include/babeltrace2/graph/component-class-dev.h +++ b/include/babeltrace2/graph/component-class-dev.h @@ -279,18 +279,23 @@ The available component class methods to implement are: Get supported \bt_mip (MIP) versions
- Called within bt_get_greatest_operative_mip_version() to get the + Called within + bt_get_greatest_operative_mip_version() or + bt_get_greatest_operative_mip_version_with_restriction() to get the set of MIP versions that an eventual \bt_comp supports. This is a \ref api-comp-cls-dev-class-meth "class method" because - you can call bt_get_greatest_operative_mip_version() before you even - create a trace processing \bt_graph. + you can call + bt_get_greatest_operative_mip_version() or + bt_get_greatest_operative_mip_version_with_restriction() before you + even create a trace processing \bt_graph. In this method, you receive initialization parameters as the \bt_p{params} parameter and initialization method data as the \bt_p{initialize_method_data}. Those parameters are set when bt_component_descriptor_set_add_descriptor() is called, before - bt_get_greatest_operative_mip_version() is called. + bt_get_greatest_operative_mip_version() or + bt_get_greatest_operative_mip_version_with_restriction() is called. Considering those initialization parameters, you need to fill the received \bt_uint_rs \bt_p{supported_versions} with the rangs of @@ -658,7 +663,8 @@ to \bt_p{supported_versions}. @param[in] logging_level Logging level to use during this method's execution, as passed as the \bt_p{logging_level} parameter of - bt_get_greatest_operative_mip_version(). + bt_get_greatest_operative_mip_version() and + bt_get_greatest_operative_mip_version_with_restriction(). @param[in] supported_versions \bt_c_uint_rs to which to add the ranges of supported MIP versions of an eventual instance of \bt_p{self_component_class} considering @@ -716,7 +722,8 @@ to \bt_p{supported_versions}. @param[in] logging_level Logging level to use during this method's execution, as passed as the \bt_p{logging_level} parameter of - bt_get_greatest_operative_mip_version(). + bt_get_greatest_operative_mip_version() and + bt_get_greatest_operative_mip_version_with_restriction(). @param[in] supported_versions \bt_c_uint_rs to which to add the ranges of supported MIP versions of an eventual instance of \bt_p{self_component_class} considering @@ -774,7 +781,8 @@ to \bt_p{supported_versions}. @param[in] logging_level Logging level to use during this method's execution, as passed as the \bt_p{logging_level} parameter of - bt_get_greatest_operative_mip_version(). + bt_get_greatest_operative_mip_version() and + bt_get_greatest_operative_mip_version_with_restriction(). @param[in] supported_versions \bt_c_uint_rs to which to add the ranges of supported MIP versions of an eventual instance of \bt_p{self_component_class} considering diff --git a/include/babeltrace2/graph/component-descriptor-set.h b/include/babeltrace2/graph/component-descriptor-set.h index 918bff40..bc109b86 100644 --- a/include/babeltrace2/graph/component-descriptor-set.h +++ b/include/babeltrace2/graph/component-descriptor-set.h @@ -26,7 +26,8 @@ extern "C" { @brief Set of descriptors of prospective \bt_p_comp to use with - bt_get_greatest_operative_mip_version(). + bt_get_greatest_operative_mip_version() or + bt_get_greatest_operative_mip_version_with_restriction(). A component descriptor set is an \em unordered set of component descriptors. @@ -50,7 +51,8 @@ trace processing \bt_graph without actually doing it: functions. As of \bt_name_version_min_maj, the only use case of a component -descriptor set is bt_get_greatest_operative_mip_version(). This +descriptor set is bt_get_greatest_operative_mip_version() and +bt_get_greatest_operative_mip_version_with_restriction(). This function computes the greatest \bt_mip version which you can use to create a trace processing graph to which you intend to \ref api-graph-lc-add "add components" described by a set of diff --git a/include/babeltrace2/graph/message.h b/include/babeltrace2/graph/message.h index f634f888..e53d19f3 100644 --- a/include/babeltrace2/graph/message.h +++ b/include/babeltrace2/graph/message.h @@ -813,8 +813,7 @@ For example: iterator inactivity. The MIP has a version which is a single major number, independent from -the \bt_name project's version. As of \bt_name_version_min_maj, the only -available MIP version is 0. +the \bt_name project's version. If what the MIP covers changes in a breaking or semantical way in the future, the MIP and \bt_name's minor versions will be bumped. @@ -833,8 +832,9 @@ initialization time, making the corresponding bt_graph_add_*_component*() call fail too. To avoid any surprise, you can create a \bt_comp_descr_set with descriptors of the components you intend to add to a trace processing graph and call -bt_get_greatest_operative_mip_version() to get the greatest (most -recent) MIP version you can use. +bt_get_greatest_operative_mip_version() or +bt_get_greatest_operative_mip_version_with_restriction() to get the +greatest (most recent) MIP version you can use. To get the library's latest MIP version, use bt_get_maximal_mip_version(). @@ -3114,7 +3114,8 @@ This macro effectively moves a message reference from the expression /*! @brief - Status codes for bt_get_greatest_operative_mip_version(). + Status codes for bt_get_greatest_operative_mip_version() + and bt_get_greatest_operative_mip_version_with_restriction(). */ typedef enum bt_get_greatest_operative_mip_version_status { /*! @@ -3150,21 +3151,9 @@ typedef enum bt_get_greatest_operative_mip_version_status { component descriptors \bt_p{component_descriptors}, and sets \bt_p{*mip_version} to the result. -This function calls the -\link api-comp-cls-dev-meth-mip "get supported MIP versions"\endlink -method for each component descriptor in \bt_p{component_descriptors}, -and then returns the greatest common (operative) MIP version, if any. -The "get supported MIP versions" method receives \bt_p{logging_level} as -its \bt_p{logging_level} parameter. - -If this function does not find an operative MIP version for the -component descriptors of \bt_p{component_descriptors}, it returns -#BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH. - -@note - As of \bt_name_version_min_maj, because bt_get_maximal_mip_version() - returns 0, this function always sets \bt_p{*mip_version} to - 0 on success. +This function is equivalent to calling +bt_get_greatest_operative_mip_version_with_restriction() with +\bt_p{mip_version_restriction} set to \c NULL (no restriction). @param[in] component_descriptors Component descriptors for which to get the supported MIP versions @@ -3193,6 +3182,10 @@ component descriptors of \bt_p{component_descriptors}, it returns \bt_p{component_descriptors} contains one or more component descriptors. @bt_pre_not_null{mip_version} + +@sa bt_get_greatest_operative_mip_version_with_restriction() — + Computes the greatest MIP version for specific components + with a MIP version restriction. */ extern bt_get_greatest_operative_mip_version_status bt_get_greatest_operative_mip_version( @@ -3200,6 +3193,90 @@ bt_get_greatest_operative_mip_version( bt_logging_level logging_level, uint64_t *mip_version) __BT_NOEXCEPT; +/*! +@brief + Computes the greatest \bt_mip version, restricted to the set of + versions \bt_p{mip_version_restriction}, which + you can use to create a trace processing \bt_graph to which you + intend to \ref api-graph-lc-add "add components" described by the + component descriptors \bt_p{component_descriptors}, and sets + \bt_p{*mip_version} to the result. + +This function calls the +\link api-comp-cls-dev-meth-mip "get supported MIP versions"\endlink +method for each component descriptor in \bt_p{component_descriptors}, +and then sets \bt_p{*mip_version} to the greatest common (operative) +MIP version which is part of the set \bt_p{mip_version_restriction}, +if any. The "get supported MIP versions" method receives +\bt_p{logging_level} as its \bt_p{logging_level} parameter. + +For example, if all the components would support both MIP +versions 0 and 1, +but \bt_p{mip_version_restriction} only contains the +[0, 0] range, then this function sets \bt_p{*mip_version} +to 0. + +If \bt_p{mip_version_restriction} is \c NULL, then it's equivalent to +the single range [0, \bt_max_mip_version], that is, all the +possible MIP versions as of \bt_name_version_min_maj. + +If this function doesn't find an operative MIP version within +\bt_p{mip_version_restriction} for the component descriptors of +\bt_p{component_descriptors}, then it returns +#BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH. + +@param[in] component_descriptors + Component descriptors for which to get the supported MIP versions + to compute the greatest operative MIP version. +@param[in] logging_level + Logging level to use when calling the "get supported MIP versions" + method for each component descriptor in + \bt_p{component_descriptors}. +@param[in] mip_version_restriction + @parblock + Set of MIP versions of which \bt_p{*mip_version} must be part of. + + Can be \c NULL. + @endparblock +@param[out] mip_version + On success, \bt_p{*mip_version} is the greatest + operative MIP version, within \bt_p{mip_version_restriction}, of + all the component descriptors in \bt_p{component_descriptors}. + +@retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK + Success. +@retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH + No operative MIP version exists within + \bt_p{mip_version_restriction} for the component descriptors of + \bt_p{component_descriptors}. +@retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR + Out of memory. +@retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR + Other error. + +@bt_pre_not_null{component_descriptors} +@pre + \bt_p{component_descriptors} contains one or more component + descriptors. +@pre + If \bt_p{mip_version_restriction} is not \c NULL, + then no upper value within the ranges of + \bt_p{mip_version_restriction} is greater + than \bt_max_mip_version + (the return value of bt_get_maximal_mip_version()). +@bt_pre_not_null{mip_version} + +@sa bt_get_greatest_operative_mip_version() — + Computes the greatest MIP version for specific components. +*/ +extern enum bt_get_greatest_operative_mip_version_status +bt_get_greatest_operative_mip_version_with_restriction( + const struct bt_component_descriptor_set *comp_descr_set, + enum bt_logging_level log_level, + const bt_integer_range_set_unsigned *mip_version_restriction, + uint64_t *mip_version) + __BT_NOEXCEPT; + /*! @brief Returns the maximal available \bt_mip version as of diff --git a/include/babeltrace2/logging.h b/include/babeltrace2/logging.h index 14660186..56c948fd 100644 --- a/include/babeltrace2/logging.h +++ b/include/babeltrace2/logging.h @@ -60,8 +60,9 @@ not control the logging level of: - A \ref api-qexec "query operation": bt_query_executor_set_logging_level() controls this. -- The bt_get_greatest_operative_mip_version() operation: its - \bt_p{logging_level} parameter controls this. +- The bt_get_greatest_operative_mip_version() or + bt_get_greatest_operative_mip_version_with_restriction() operation: + its \bt_p{logging_level} parameter controls this. As of \bt_name_version_min_maj, there's no module-specific logging level control: bt_logging_set_global_level() sets the logging level of all the diff --git a/src/lib/graph/mip.c b/src/lib/graph/mip.c index 46670185..c5858ea8 100644 --- a/src/lib/graph/mip.c +++ b/src/lib/graph/mip.c @@ -218,6 +218,7 @@ end: static bt_get_greatest_operative_mip_version_status find_greatest_compatible_mip_version( const GPtrArray *supported_ranges, + const bt_integer_range_set_unsigned *mip_version_restriction, uint64_t *operative_mip_version) { bool versions[MAX_MIP_VERSION + 1]; @@ -230,6 +231,20 @@ bt_get_greatest_operative_mip_version_status find_greatest_compatible_mip_versio versions[v] = true; } + /* + * Disable specific versions based on `mip_version_restriction`, + * if set. + */ + if (mip_version_restriction) { + for (v = 0; v <= MAX_MIP_VERSION; ++v) { + if (!unsigned_integer_range_set_contains( + bt_integer_range_set_unsigned_as_range_set_const( + mip_version_restriction), v)) { + versions[v] = false; + } + } + } + /* * Go over each (soon-to-be) component's range set of support MIP * versions. @@ -266,10 +281,11 @@ end: BT_EXPORT enum bt_get_greatest_operative_mip_version_status -bt_get_greatest_operative_mip_version( +bt_get_greatest_operative_mip_version_with_restriction( const struct bt_component_descriptor_set *comp_descr_set, enum bt_logging_level log_level, - uint64_t *operative_mip_version) + const bt_integer_range_set_unsigned *mip_version_restriction, + uint64_t *mip_version) { int status; GPtrArray *supported_ranges; @@ -281,7 +297,7 @@ bt_get_greatest_operative_mip_version( BT_ASSERT_PRE_NO_ERROR(); BT_ASSERT_PRE_COMP_DESCR_SET_NON_NULL(comp_descr_set); BT_ASSERT_PRE_NON_NULL("operative-mip-version-output", - operative_mip_version, + mip_version, "Operative MIP version (output)"); BT_ASSERT_PRE("component-descriptor-set-is-not-empty", comp_count > 0, @@ -315,10 +331,10 @@ bt_get_greatest_operative_mip_version( } status = find_greatest_compatible_mip_version( - supported_ranges, operative_mip_version); + supported_ranges, mip_version_restriction, mip_version); if (status == BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK) { BT_LIB_LOGD("Found a compatible MIP version: version=%d", - *operative_mip_version); + *mip_version); } else { BT_LIB_LOGD("Failed to find a compatible MIP version: status=%s", bt_common_func_status_string(status)); @@ -329,6 +345,17 @@ end: return status; } +BT_EXPORT +enum bt_get_greatest_operative_mip_version_status +bt_get_greatest_operative_mip_version( + const struct bt_component_descriptor_set *comp_descr_set, + enum bt_logging_level log_level, + uint64_t *mip_version) +{ + return bt_get_greatest_operative_mip_version_with_restriction( + comp_descr_set, log_level, NULL, mip_version); +} + BT_EXPORT uint64_t bt_get_maximal_mip_version(void) { -- 2.34.1