Class IMetricsSource

• Defined in File metrics-source.h

Inheritance Relationships

Derived Type

• public gpa::metrics::IMetricsSourceComposite (Class IMetricsSourceComposite)

Class Documentation

class IMetricsSource

Interface used to get consistent details about the various metrics provided by a MetricsSource object.

Subclassed by gpa::metrics::IMetricsSourceComposite

Public Functions

virtual ~IMetricsSource()

virtual MetricsSourceType Type(MetricsSourceData *pMetricsSourceData = nullptr) const = 0

Returns the type of MetricsSource instantiated if ready for usage, and optionally provides additional data about the metrics it provides when the type is NOT kComposite. Otherwise, it returns kInvalid.

virtual uint32_t NumAvailableMetrics() const = 0

Returns the total number of available metrics from all of metrics source's groups.

Note

Use to determine range of valid global metric indices: [0, IMetricsSource::NumAvailableMetrics).

Note

If metrics prototypes are supported by the GPU (as reported by IMetricsSource::NumMetricPrototypes) and any were instantiated (IMetricsSource::InstantiateMetricPrototype), the total number of available metrics will increase after IMetricsSource::PrepareInstantiatedMetricsForUsage is called successfully.

virtual MetricDesc const &MetricDescription(uint32_t const metricIndex) const = 0

Returns a reference to the description of a metric specified using its global metric index in the metrics source.

Note

If the global metric index is out of range, a metric description initialized with invalid fields is returned.

Note

If metrics prototypes are supported by the GPU and any were instantiated, the number of available metric descriptions will increase after the instantiated metrics are prepared.

Parameters

metricIndex -- [in] Global metric index in range: [0, IMetricsSource::NumAvailableMetrics).

virtual uint32_t NumMetricGroups() const = 0

Returns the number of available metric groups in the metrics source.

Note

Use to determine range of valid metric group indices: [0, IMetricsSource::NumMetricGroups).

Note

If metrics prototypes are supported by the GPU and any were instantiated, the available number of metric groups will increase after the instantiated metrics are prepared.

virtual uint32_t NumMetricsInGroup(uint32_t const metricGroupIndex) const = 0

Returns the number of available metrics for a group specified using its group index in the metrics source.

Note

If the group index is out of range, 0 is returned.

Note

If metrics prototypes are supported by the GPU and any were instantiated, the number of valid metric group indices will increase after the instantiated metrics are prepared.

Parameters

metricGroupIndex -- [in] Group index in range: [0, IMetricsSource::NumMetricGroups).

virtual int32_t GroupContainingMetric(uint32_t const metricIndex) const = 0

Returns group index for a metric specified using its global metric index in the metrics source.

Note

If the global metric index is out of range, an invalid group index is returned such as -1.

Note

If metrics prototypes are supported by the GPU and any were instantiated, the number of valid global metric indices will increase after the instantiated metrics are prepared.

Parameters

metricIndex -- [in] Global metric index in range: [0, IMetricsSource::NumAvailableMetrics).

virtual IMetricGroup const *MetricGroup(uint32_t metricGroupIndex) const = 0

Returns IMetricGroup interface for a group specified using its group index in the metrics source.

Note

If the group index is out of range, nullptr is returned.

Note

If metrics prototypes are supported by the GPU and any were instantiated, the number of valid metric group indices will increase after the instantiated metrics are prepared.

Parameters

metricGroupIndex -- [in] Group index in range: [0, IMetricsSource::NumMetricGroups).

virtual uint32_t NumMetricPrototypes() const = 0

Returns the number of metric prototypes in the metrics source that can be instantiated using IMetricsSource::InstantiateMetricPrototype.

Note

Use to determine range of valid metric prototype indices: [0, IMetricsSource::NumMetricPrototypes).

Note

Zero is returned when no metric prototypes are supported. Only the Intel MD library query-based metrics source (kQueryBased_IntelMD) provides support for metric prototypes on Intel GPUs that support them.

virtual Result MetricPrototypeDescription(uint32_t const metricPrototypeIndex, MetricDesc *const pMetricPrototypeDescription) const = 0

Retrieves the description for a metric prototype specified using its metric prototype index.

Note

The metric prototype's description index will be kInvalidMetricIndex, and its groupId will be kInvalidGroupIndex.

Parameters

• metricPrototypeIndex -- [in] Prototype index in range: [0, IMetricsSource::NumMetricPrototypes).

• pMetricPrototypeDescription -- [inout] Pointer to description of the prototype that will be initialized upon success.

Returns

Upon success, kSuccess is returned and the contents of the description provided are updated for the specified metric prototype. Otherwise, a failure result is returned.

virtual Result InstantiateMetricPrototype(uint32_t const metricPrototypeIndex, char const *pNameOverride, char const *pSymbolicNameOverride, char const *pDescriptionOverride, char const *pUnitsOverride, uint32_t optionCount, MetricInstanceOption const *pOptionArray, uint32_t *pInstantiatedMetricIndex) = 0

Instantiates a metric prototype configuration intended to be used, including validating any requested options.

Note

All available options that can be requested, are reported in the associated metric prototype description. For each option, it includes the type of value it can be set to, and the available range/set of values of that type that can be specified.

Note

Every option reported as available can be requested in one metric prototype configuration, with the exception of the normalization options which are mutually exclusive (thus only one as be requested at a time).

Note

A metric prototype can be instantiated multiple times, once for each different configuration (which consists of different options and/or names/overrides). Each instatantiation of a metric prototype configuration will be assigned and associated with a different metric group after they are prepared for usage via calling IMetricsSource::PrepareInstantiatedMetricsForUsage. Afterwards, each associated instantiated metric description will identify the associated group index.

Warning

The provided instantiated metric index will change if IMetricsSource::RemoveInstantiatedMetric is used to remove any with an index less than the newly instantiated metric.

Parameters

• metricPrototypeIndex -- [in] Prototype index in range: [0, IMetricsSource::NumMetricPrototypes).

• pNameOverride -- [in] Optional pointer to null terminated char array with a metric name to use for the metric instead of the provided/generated one (in MetricDesc struct and retuned by IMetric). Use nullptr to keep the provided one.

• pSymbolicNameOverride -- [in] Optional pointer to null terminated char array with a symbol name to use for the metric instead of the provided one (in MetricDesc struct and retuned by IMetric). Use nullptr to keep the provided one.

• pDescriptionOverride -- [in] Optional pointer to null terminated char array with a description to use for the metric instead of the provided one (in MetricDesc struct and retuned by IMetric). Use nullptr to keep the provided one.

• pUnitsOverride -- [in] Optional pointer to null terminated char array with a units name to use for the metric instead of the provided one (in MetricDesc struct and retuned by IMetric). Use nullptr to keep the provided one.

• optionCount -- [in] Number of requested option elements provided in the array pointed at by pOptionArray. Specify zero if none are needed.

• pOptionArray -- [in] Optional pointer to an array of requested options with optionCount elements in it. Review notes for option requirements. Specify nullptr if there are no options requested.

• pInstantiatedMetricIndex -- [inout] Optional pointer to an unsigned integer that will hold the index of the instantiated metric upon function succcess. Review warnings.

Returns

Upon success, kSuccess is returned, the requested metric prototype configuration is instantiated, and the index of the instantiated metric is initialized if a pointer to one was provided. Upon failure, a failure result is returned.

virtual Result RemoveInstantiatedMetric(uint32_t const instantiatedMetricIndex) = 0

Removes an instantiated metric prototype.

Warning

The indices of any other previously instantiated metrics, with an index larger than the one removed will be changed.

Parameters

instantiatedMetricIndex -- [in] Instantiated metric index in range: [0, IMetricsSource::NumInstantiatedMetrics).

Returns

Upon success, kSuccess is returned, the specified instantiated metric prototype is removed and will not be an available metric after IMetricsSource::PrepareInstantiatedMetricsForUsage is called. Otherwise, a failure result is returned.

virtual Result PrepareInstantiatedMetricsForUsage(char const *pGroupNamePrefixOverride, char const *pGroupSymbolicNamePrefixOverride) = 0

Prepares the instantiated metric prototypes to be used by creating all needed metric groups and assigning the metrics to them.

Note

All instantiated metrics prototypes are reported in the new IMetricsSource::NumAvailableMetrics count and thier descriptions obtained using IMetricsSource::MetricDescription. The description will match the ones that can be obtained using IMetricsSource::InstantiatedMetricDescription, and will have their metric index and groupId fields initialized with valid values.

Note

All new metric groups associated with the instantiated metric prototypes are reported in the new IMetricsSource::NumMetricGroups count and can be obtained using IMetricsSource::MetricGroup. They can all be immediately used for metrics collection.

Note

Attempts to re-prepare the metrics source by calling it multiple times will fail.

Parameters

• pGroupNamePrefixOverride -- [in] Optional pointer to null terminated char array with a group name prefix that will be used for all created metric groups. Use nullptr to use the default ("Custom Metric Group").

• pGroupSymbolicNamePrefixOverride -- [in] Optional pointer to null terminated char array with a group symbol name prefix that will be used for all created metric groups. Use nullptr to use the default ("CustomMetricGroup").

Returns

Upon success, kSuccess is returned and the metrics source will be "prepared" with all instantiated metric prototypes added to as many additional metric groups as needed (the quantity of which is undefined as there are complex, non- programmatically limits to which metric prototypes can be added to a group and how many can be added to each one). Note that no metric prototypes need to be instantiated. Otherwise, a failure result is returned.

virtual uint32_t NumInstantiatedMetrics() const = 0

Returns the number of instantiated metric prototypes.

Note

Use to determine range of valid instantiated metrics indices: [0, IMetricsSource::NumInstantiatedMetrics).

virtual MetricDesc const &InstantiatedMetricDescription(uint32_t const instantiatedMetricIndex) const = 0

Returns a reference to an instantiated metric description using the associated instantiated metric index.

Note

Prior to IMetricsSource::PrepareInstantiatedMetricsForUsage being called successfully, the instantiated metric's description index will be kInvalidMetricIndex and its groupId will be kInvalidGroupIndex.

Note

If the instantiated metric index is out of range, a description initialized with invalid fields is returned.

Parameters

instantiatedMetricIndex -- [in] Instantiated metric index in range: [0, IMetricsSource::NumInstantiatedMetrics).