Get supported \bt_mip (MIP) versions
</dt>
<dd>
- 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
@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
@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
@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
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.
<code>bt_graph_add_*_component*()</code> 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().
/*!
@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 {
/*!
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
\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(
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
+ <strong>On success</strong>, \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
+ <strong>If \bt_p{mip_version_restriction} is not \c NULL</strong>,
+ 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
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];
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.
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;
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,
}
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));
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)
{
projects / babeltrace.git / commitdiff
