NvRules API :: Nsight Compute Documentation

-->
NvRules API (PDF) - v2023.2.0 (older) - Last updated May 22, 2023 - Send Feedback

## 2. Data Structures

Here are the data structures with brief descriptions:

NV::​Rules::​IAction
  Action interface
NV::​Rules::​IContext
  Context interface
NV::​Rules::​IController
  Controller interface
NV::​Rules::​IEvaluator
  Evaluator interface
NV::​Rules::​IFrontend
  Frontend interface
NV::​Rules::​IMetric
  Metric interface
NV::​Rules::​INvtxDomainInfo
  NvtxDomainInfo interface
NV::​Rules::​INvtxRange
  NvtxRange interface
NV::​Rules::​INvtxState
  NvtxState interface
NV::​Rules::​IRange
  Range interface
NV::​Rules::​ISourceInfo
  SourceInfo interface

### 2.1. NV::Rules::IAction Class Reference

### [NvRules Python garbage-collected classes.]

Represents an activity such as a CUDA kernel on a single range, for which zero or more metrics were collected

#### Public Enumerations

enum NameBase
  Basis for action names.

#### Public Member Functions

virtual IMetric* add_double_metric ( const char* value_name, IMetric::​ValueKind value_kind, double value ) =0
  Add a single floating point metric to this action.
virtual IMetric* add_integer_metric ( const char* value_name, IMetric::​ValueKind value_kind, uint64_t value ) =0
  Add a single integer metric to this action.
virtual PYRETURN IMutableMetric* add_metric ( const char* value_name ) =0
  Add a single mutable metric to this action.
virtual IMetric* add_string_metric ( const char* value_name, IMetric::​ValueKind value_kind, const char* value ) =0
  Add a single string metric to this action.
virtual IMetric* metric_by_name ( const char* metric_name ) =0
  Get a single metric by name.
virtual std::​set < std::​string > metric_names ( ) =0
  Get the set of metric names.
virtual const char* name ( NameBase base = NameBase::FUNCTION ) =0
  Get the action name.
virtual INvtxState* nvtx_state ( ) =0
  Get the NVTX state associated with this action.
virtual std::​string ptx_by_pc ( uint64_t address ) =0
  Get the PTX for a function address within this action.
virtual std::​string sass_by_pc ( uint64_t address ) =0
  Get the disassembled SASS for a function address within this action.
virtual std::​map < std::​string, std::​string > source_files ( ) =0
  Get the source files associated with an action.
virtual ISourceInfo* source_info ( uint64_t address ) =0
  Get the source info for a function address within this action.

#### Enumerations

enum NV::​Rules::​IAction::NameBase [inherited]

  The basis determines how the action name is represented when calling name. `FUNCTION` is the minimal base name without parameters or return value. `DEMANGLED` is the demangled name, including parameters and return value. `MANGLED` is the mangled name, including parameters and return value.

  ###### Values

  FUNCTION
  DEMANGLED
  MANGLED

#### Member Functions

virtual IMetric* NV::​Rules::​IAction::add_double_metric ( const char* value_name, IMetric::​ValueKind value_kind, double value ) [inherited, pure virtual]
  Add a single floating point metric to this action.

  ###### Returns

  the new IMetric

  ###### Description

  Add a single floating point metric with name `value_name` and kind `value_kind` to this action

virtual IMetric* NV::​Rules::​IAction::add_integer_metric ( const char* value_name, IMetric::​ValueKind value_kind, uint64_t value ) [inherited, pure virtual]
  Add a single integer metric to this action.

  ###### Returns

  the new IMetric

  ###### Description

  Add a single integer metric to with name `value_name` and kind `value_kind` this action.

virtual PYRETURN IMutableMetric* NV::​Rules::​IAction::add_metric ( const char* value_name ) [inherited, pure virtual]
  Add a single mutable metric to this action.

  ###### Returns

  the new IMutableMetric

  ###### Description

  Add a single, mutable metric with name `value_name` to this action. The metric is not initialized with any kind or value and needs to be assigned proper values and/or instances afterwards. IMutableMetric provides the following interface:

  void set_double(IMetric::ValueKind value_kind, double value)

  Return true if the value was set, false otherwise. Assign the metric a floating-point value of value_kind Acceptable kinds are FLOAT, DOUBLE or ANY (for which the implementation chooses the kind internally)

  bool set_double(size_t instance, IMetric::ValueKind value_kind, double value)

  Return true if the instance value was set, false otherwise. Assign the metric an instance floating-point value of value_kind Acceptable kinds are FLOAT, DOUBLE or ANY (for which the implementation chooses the kind internally)

  void set_uint64(IMetric::ValueKind value_kind, uint64_t value)

  Return true if the value was set, false otherwise. Assign the metric an integer value of value_kind Acceptable kinds are UINT32, UINT64 or ANY (for which the implementation chooses the kind internally)

  bool set_uint64(size_t instance, IMetric::ValueKind value_kind, uint64_t value)

  Return true if the instance value was set, false otherwise. Assign the metric an instance integer value of value_kind Acceptable kinds are UINT32, UINT64 or ANY (for which the implementation chooses the kind internally)

  void set_string(IMetric::ValueKind value_kind, const char* value)

  Return true if the value was set, false otherwise. Assign the metric a string value of value_kind Acceptable kinds are STRING or ANY (for which the implementation chooses the kind internally)

  bool set_string(size_t instance, IMetric::ValueKind value_kind, const char* value)

  Return true if the instance value was set, false otherwise. Assign the metric an instance string value of value_kind Acceptable kinds are STRING or ANY (for which the implementation chooses the kind internally)

  IMutableMetric *mutable_correlation_ids()

  Returns a new, mutable metric object representing the correlation IDs for the metric's instance values. Correlation IDs are used to associate instance values with the "instance" their value represents. In the returned new metric object, the correlation IDs are that object's instance values.

virtual IMetric* NV::​Rules::​IAction::add_string_metric ( const char* value_name, IMetric::​ValueKind value_kind, const char* value ) [inherited, pure virtual]
  Add a single string metric to this action.

  ###### Returns

  the new IMetric

  ###### Description

  Add a single string metric with name `value_name` and kind `value_kind` to this action

virtual IMetric* NV::​Rules::​IAction::metric_by_name ( const char* metric_name ) [inherited, pure virtual]
  Get a single metric by name.

  ###### Description

  Get a single IMetric by `metric_name`

virtual std::​set < std::​string > NV::​Rules::​IAction::metric_names ( ) [inherited, pure virtual]
  Get the set of metric names.

  ###### Description

  Get the set of metrics available for this action

virtual const char* NV::​Rules::​IAction::name ( NameBase base = NameBase::FUNCTION ) [inherited, pure virtual]
  Get the action name.

  ###### Description

  Get the action name

virtual INvtxState* NV::​Rules::​IAction::nvtx_state ( ) [inherited, pure virtual]
  Get the NVTX state associated with this action.

  ###### Returns

  a new INvtxState object if any NVTX state is available for this action.

  ###### Description

virtual std::​string NV::​Rules::​IAction::ptx_by_pc ( uint64_t address ) [inherited, pure virtual]
  Get the PTX for a function address within this action.

  ###### Returns

  PTX string. An empty string is returned if no PTX is associated with this address

  ###### Description

  Get the PTX for a function `address` within this action. The address is expected to be absolute, i.e. as obtained from the correlation IDs of source-correlated metrics.

virtual std::​string NV::​Rules::​IAction::sass_by_pc ( uint64_t address ) [inherited, pure virtual]
  Get the disassembled SASS for a function address within this action.

  ###### Returns

  SASS string. An empty string is returned if no SASS is associated with this address

  ###### Description

  Get the disassembled SASS for a function `address` within this action. The address is expected to be absolute, i.e. as obtained from the correlation IDs of source-correlated metrics. The SASS may include formatting whitespace as generated by the disassembler.

virtual std::​map < std::​string, std::​string > NV::​Rules::​IAction::source_files ( ) [inherited, pure virtual]
  Get the source files associated with an action.

  ###### Returns

  a map from file name to file content

  ###### Description

  Get the map of source files associated with this action, along with their content. If content is not available for a file (e.g. because it hadn't been imported into the report), the file name will map to an empty string.

virtual ISourceInfo* NV::​Rules::​IAction::source_info ( uint64_t address ) [inherited, pure virtual]
  Get the source info for a function address within this action.

  ###### Returns

  a new ISourceInfo object if it is available

  ###### Description

  Get the source info for `address` within this action. Addresses are commonly obtained as correlation ids of source-correlated metrics.

### 2.2. NV::Rules::IContext Class Reference

### [NvRules Tool lifetime-managed classes.]

The rule context provides the rule with access to all collected data, properties and means to relay results back to the caller.

#### Public Member Functions

virtual IController* controller ( ) =0
  Get the controller object.
virtual IFrontend* frontend ( ) =0
  Get the frontend object.
virtual std::​string get_version ( ) =0
  Get version number of this interface.
virtual bool handle_exception ( const char* msg ) =0
  Context exception handler.
virtual size_t num_ranges ( ) =0
  Get the number of available ranges.
virtual IRange* range_by_idx ( size_t idx ) =0
  Get a single range by index.

#### Member Functions

virtual IController* NV::​Rules::​IContext::controller ( ) [inherited, pure virtual]
  Get the controller object.

  ###### Description

  Get the IController object

virtual IFrontend* NV::​Rules::​IContext::frontend ( ) [inherited, pure virtual]
  Get the frontend object.

  ###### Description

  Get the IFrontend object

virtual std::​string NV::​Rules::​IContext::get_version ( ) [inherited, pure virtual]
  Get version number of this interface.

  ###### Description

  Returns the version number of this interface as a string of the form <year>.<major>.<minor> It matches the Nsight Compute version this interface originates from.

virtual bool NV::​Rules::​IContext::handle_exception ( const char* msg ) [inherited, pure virtual]
  Context exception handler.

  ###### Description

  Should return true if a python exception should be set, false otherwise

virtual size_t NV::​Rules::​IContext::num_ranges ( ) [inherited, pure virtual]
  Get the number of available ranges.

  ###### Description

  Get the number of available ranges

virtual IRange* NV::​Rules::​IContext::range_by_idx ( size_t idx ) [inherited, pure virtual]
  Get a single range by index.

  ###### Description

  Get a single IRange by index

### 2.3. NV::Rules::IController Class Reference

### [NvRules Tool lifetime-managed classes.]

The controller can be used to interact with the tool runtime, e.g. to signal the tools to propose a follow-up rule.

#### Public Member Functions

virtual void propose_rule ( const char* rule ) =0

#### Member Functions

virtual void NV::​Rules::​IController::propose_rule ( const char* rule ) [inherited, pure virtual]

  ###### Description

  Propose the specified `rule` in the current context

### 2.4. NV::Rules::IEvaluator Class Reference

### [NvRules Tool lifetime-managed classes.]

The evaluator is used during rule setup to pass information about rule dependencies to the tool. For most cases, its Python wrapper functions can be used instead for convenience.

#### Public Member Functions

virtual std::​string get_version ( ) =0
  Get version number of this interface.
virtual bool handle_exception ( const char* msg ) =0
  Context exception handler.
virtual void require_metric ( const char* metric ) =0
virtual void require_rule ( const char* rule ) =0

#### Member Functions

virtual std::​string NV::​Rules::​IEvaluator::get_version ( ) [inherited, pure virtual]
  Get version number of this interface.

  ###### Description

  Returns the version number of this interface as a string of the form <year>.<major>.<minor> It matches the Nsight Compute version this interface originates from.

virtual bool NV::​Rules::​IEvaluator::handle_exception ( const char* msg ) [inherited, pure virtual]
  Context exception handler.

  ###### Description

  Should return true if a python exception should be set, false otherwise

virtual void NV::​Rules::​IEvaluator::require_metric ( const char* metric ) [inherited, pure virtual]

  ###### Description

  Define that the specified `metric` must have been collected in order for the calling rule to be applied.

virtual void NV::​Rules::​IEvaluator::require_rule ( const char* rule ) [inherited, pure virtual]

  ###### Description

  Define that the specified `rule` must be available and ready to be applied in order for the calling rule to be applied itself.

### 2.5. NV::Rules::IFrontend Class Reference

### [NvRules Tool lifetime-managed classes.]

The frontend is responsible for relaying messages and results to the caller via user interfaces, logs or output files.

#### Public Enumerations

enum MarkerKind
  Marker Kind.
enum MsgType
  Message type.
enum Severity
  Focus metric severity.
enum SpeedupType
  Speedup estimation type.

#### Public Member Functions

virtual bool focus_metric ( int message_id, const char* metric_name, double metric_value, Severity severity, const char* info ) =0
  Rule focus metric message.
virtual void load_chart_from_file ( const char* filename ) =0
virtual int message ( MsgType type, const char* str, const char* name = nullptr ) =0
  Rule result message.
virtual int message ( const char* str, const char* name = nullptr ) =0
  Rule result message.
virtual void source_marker ( const char* str, uint64_t address_or_line, MarkerKind kind, const char* file_name, MsgType type = MsgType::MSG_NONE ) =0
  Rule source marker.
virtual void source_marker ( const char* str, uint64_t address_or_line, MarkerKind kind, MsgType type = MsgType::MSG_NONE ) =0
  Rule source marker.
virtual bool speedup ( int message_id, SpeedupType type, double estimated_speedup ) =0
  Rule estimated speedup message.

#### Enumerations

enum NV::​Rules::​IFrontend::MarkerKind [inherited]

  The kind of marker that is created in the Source Page with source_marker. `SASS` The marker will be associated with a SASS instruction. `SOURCE` The marker will be associated with a Source line.

  ###### Values

  SASS
  SOURCE
enum NV::​Rules::​IFrontend::MsgType [inherited]

  The type a message to the frontend represents when calling message. `MSG_NONE` No specific type for this message. `MSG_OK` The message is informative. `MSG_OPTIMIZATION` The message represents a suggestion for performance optimization. `MSG_WARNING` The message represents a warning or fixable issue. `MSG_ERROR` The message represents an error, potentially in executing the rule.

  ###### Values

  MSG_NONE
  MSG_OK
  MSG_OPTIMIZATION
  MSG_WARNING
  MSG_ERROR
enum NV::​Rules::​IFrontend::Severity [inherited]

  The severity a focus metric represents when calling focus_metric. The severity can be used by the rule system client when processing the focus metric. `SEVERITY_DEFAULT` The default severity. `SEVERITY_LOW` Severity if low. `SEVERITY_HIGH` Severity if high.

  ###### Values

  SEVERITY_DEFAULT
  SEVERITY_LOW
  SEVERITY_HIGH
enum NV::​Rules::​IFrontend::SpeedupType [inherited]

  The type of speedup estimation used when calling speedup. `LOCAL` Only section-scope metrics were used for the calculation, potentially indicating a suboptimal approximation. `GLOBAL` Non section-scope, collectable metrics were used for the calculation, indicating the best available approximation.

  ###### Values

  LOCAL
  GLOBAL

#### Member Functions

virtual bool NV::​Rules::​IFrontend::focus_metric ( int message_id, const char* metric_name, double metric_value, Severity severity, const char* info ) [inherited, pure virtual]
  Rule focus metric message.

  ###### Description

  Issues a focus metric message to the frontend, e.g. to indicate a key metric that triggered the rule output. Can be associated with a prior message using its `message_id` . The `severity` can be used to indicate this metric's impact/severity on the result. The `info` field can be set to a descriptive string for further information, e.g. the calculation leading to this metric being focused. Returns whether the focus_metric could be set successfully for the `message_id` .

virtual void NV::​Rules::​IFrontend::load_chart_from_file ( const char* filename ) [inherited, pure virtual]

  ###### Description

  Load a ProfilerSection google protcol buffer chart from `filename`

virtual int NV::​Rules::​IFrontend::message ( MsgType type, const char* str, const char* name = nullptr ) [inherited, pure virtual]
  Rule result message.

  ###### Description

  Issues a message `str` with a specific message `type` and optional name `name` to the frontend. Returns a message ID that is unique in this rule invocation.

virtual int NV::​Rules::​IFrontend::message ( const char* str, const char* name = nullptr ) [inherited, pure virtual]
  Rule result message.

  ###### Description

  Issues a message `str` to the frontend with the default MsgType and optional name `name` . Returns a message ID that is unique in this rule invocation.

virtual void NV::​Rules::​IFrontend::source_marker ( const char* str, uint64_t address_or_line, MarkerKind kind, const char* file_name, MsgType type = MsgType::MSG_NONE ) [inherited, pure virtual]
  Rule source marker.

  ###### Description

  Creates a source marker with a message `str` at the source location `address_or_line` in the appropriate `kind` of source. This function supports multi-file programs, which means a `file_name` has to be specified. The `type` denotes the urgency associated with this marker and is optional.

virtual void NV::​Rules::​IFrontend::source_marker ( const char* str, uint64_t address_or_line, MarkerKind kind, MsgType type = MsgType::MSG_NONE ) [inherited, pure virtual]
  Rule source marker.

  ###### Description

  Creates a source marker with a message `str` at the source location `address_or_line` in the appropriate `kind` of source. The `type` denotes the urgency associated with this marker and is optional.

virtual bool NV::​Rules::​IFrontend::speedup ( int message_id, SpeedupType type, double estimated_speedup ) [inherited, pure virtual]
  Rule estimated speedup message.

  ###### Description

  Issues an estimated speedup to the frontend associated to the message with ID `message_id` . It indicates what speedup could potentially be achieved, when following the guidelines of the rule. The `type` of the speedup estimation indicates whether the estimate was calculated locally (`SpeedupType::LOCAL`), i.e. using metrics collect at section scope, or globally (`SpeedupType::GLOBAL`), i.e. using any metric that is collectable on the given system. Returns whether the speedup could be set successfully for the `message_id` .

### 2.6. NV::Rules::IMetric Class Reference

### [NvRules Python garbage-collected classes.]

Represents a single, named metric. A metric can carry one value or multiple, if it is an instanced metric.

#### Public Enumerations

enum MetricSubtype
  Metric subtype.
enum MetricType
  Metric type.
enum RollupOperation
  Rollup Operation.
enum ValueKind
  Metric value kind.

#### Public Member Functions

virtual double as_double ( size_t instance ) =0
  Get a value from the metric instances as double.
virtual double as_double ( ) =0
  Get the metric value as double.
virtual const char* as_string ( size_t instance ) =0
  Get a value from the metric instances as string.
virtual const char* as_string ( ) =0
  Get the metric value as string.
virtual uint64_t as_uint64 ( size_t instance ) =0
  Get a value from the metric instances as 64bit integer.
virtual uint64_t as_uint64 ( ) =0
  Get the metric value as 64bit integer.
virtual IMetric* correlation_ids ( ) =0
  Get a metric object for this metric's instance value's correlation IDs.
virtual Description description ( ) const =0
  Get the metric description.
virtual bool has_correlation_ids ( ) =0
  Check if the metric has correlation IDs.
virtual bool has_value ( ValueKind value_kind ) =0
  Check if the metric has a non-instanced value of a specific kind.
virtual bool has_value ( ) =0
  Check if the metric has a non-instanced value.
virtual ValueKind kind ( size_t instance ) =0
  Get the metric value kind for an instance value.
virtual ValueKind kind ( ) =0
  Get the metric value kind.
virtual MetricSubtype metric_subtype ( ) const =0
  Get the metric subtype.
virtual MetricType metric_type ( ) const =0
  Get the metric type.
virtual const char* name ( ) =0
  Get the metric name.
virtual size_t num_instances ( ) =0
  Get the number of instance values for this metric.
virtual RollupOperation rollup_operation ( ) const =0
  Get the type of rollup operation.
virtual Unit unit ( ) const =0
  Get the metric unit.

#### Enumerations

enum NV::​Rules::​IMetric::MetricSubtype [inherited]

  Indicates the subtype of the metric. Subtypes only apply to hardware metrics. Other metric types have subtype `None` in Python.

  ###### Values

  NONE = 0
  PEAK_SUSTAINED
  PEAK_SUSTAINED_ACTIVE
  PEAK_SUSTAINED_ACTIVE_PER_SECOND
  PEAK_SUSTAINED_ELAPSED
  PEAK_SUSTAINED_ELAPSED_PER_SECOND
  PEAK_SUSTAINED_FRAME
  PEAK_SUSTAINED_FRAME_PER_SECOND
  PEAK_SUSTAINED_REGION
  PEAK_SUSTAINED_REGION_PER_SECOND
  PER_CYCLE_ACTIVE
  PER_CYCLE_ELAPSED
  PER_CYCLE_IN_FRAME
  PER_CYCLE_IN_REGION
  PER_SECOND
  PCT_OF_PEAK_SUSTAINED_ACTIVE
  PCT_OF_PEAK_SUSTAINED_ELAPSED
  PCT_OF_PEAK_SUSTAINED_FRAME
  PCT_OF_PEAK_SUSTAINED_REGION
  MAX_RATE
  PCT
  RATIO
enum NV::​Rules::​IMetric::MetricType [inherited]

  Indicates the type of the metric. May take values `COUNTER`, `RATIO` or `THROUGHPUT` for hardware metrics, and `OTHER` for all other types (e.g. launch metrics, device attributes).

  ###### Values

  OTHER = 0
  COUNTER
  RATIO
  THROUGHPUT
enum NV::​Rules::​IMetric::RollupOperation [inherited]

  Indicates the type of operation that is used to accumulate multiple values of a given metric. May take values `AVG`, `MAX`, `MIN` and `SUM`, as well as `None`, if no such operation is specified.

  ###### Values

  NONE = 0
  AVG
  MAX
  MIN
  SUM
enum NV::​Rules::​IMetric::ValueKind [inherited]

  Indicates the kind (or type) of a metric value, metric instance value or correlation ID.

  ###### Values

  UNKNOWN
  ANY
  STRING
  FLOAT
  DOUBLE
  UINT32
  UINT64

#### Member Functions

virtual double NV::​Rules::​IMetric::as_double ( size_t instance ) [inherited, pure virtual]
  Get a value from the metric instances as double.

  ###### Description

  Get the value of metric instance `instance` as double

virtual double NV::​Rules::​IMetric::as_double ( ) [inherited, pure virtual]
  Get the metric value as double.

  ###### Description

  Get the metric value as double

virtual const char* NV::​Rules::​IMetric::as_string ( size_t instance ) [inherited, pure virtual]
  Get a value from the metric instances as string.

  ###### Description

  Get the value of metric instance `instance` as string

virtual const char* NV::​Rules::​IMetric::as_string ( ) [inherited, pure virtual]
  Get the metric value as string.

  ###### Description

  Get the metric value as string

virtual uint64_t NV::​Rules::​IMetric::as_uint64 ( size_t instance ) [inherited, pure virtual]
  Get a value from the metric instances as 64bit integer.

  ###### Description

  Get the value of metric instance `instance` as 64bit integer

virtual uint64_t NV::​Rules::​IMetric::as_uint64 ( ) [inherited, pure virtual]
  Get the metric value as 64bit integer.

  ###### Description

  Get the metric value as 64bit integer

virtual IMetric* NV::​Rules::​IMetric::correlation_ids ( ) [inherited, pure virtual]
  Get a metric object for this metric's instance value's correlation IDs.

  ###### Description

  Returns a new metric object representing the correlation IDs for the metric's instance values. Use has_correlation_ids to check if this metric has correlation IDs for its instance values. Correlation IDs are used to associate instance values with the "instance" their value represents. In the returned new metric object, the correlation IDs are that object's instance values.

virtual Description NV::​Rules::​IMetric::description ( ) const [inherited, pure virtual]
  Get the metric description.

  ###### Description

  Get a textual description of the metric

virtual bool NV::​Rules::​IMetric::has_correlation_ids ( ) [inherited, pure virtual]
  Check if the metric has correlation IDs.

  ###### Description

  If true, the metric has correlation IDs matching its instance values, which can be accessed using correlation_ids .

virtual bool NV::​Rules::​IMetric::has_value ( ValueKind value_kind ) [inherited, pure virtual]
  Check if the metric has a non-instanced value of a specific kind.

  ###### Description

  Check if the metric has a value of a specific `value_kind` . If true, the metric may still have instance values, too.

virtual bool NV::​Rules::​IMetric::has_value ( ) [inherited, pure virtual]
  Check if the metric has a non-instanced value.

  ###### Description

  Check if the metric has a non-instanced value. If true, the metric may still have instance values, too.

virtual ValueKind NV::​Rules::​IMetric::kind ( size_t instance ) [inherited, pure virtual]
  Get the metric value kind for an instance value.

  ###### Description

  Get the metric value kind for its instance value `instance` . num_instances can be used to check the total number of instance values.

virtual ValueKind NV::​Rules::​IMetric::kind ( ) [inherited, pure virtual]
  Get the metric value kind.

  ###### Description

  Get the metric value kind

virtual MetricSubtype NV::​Rules::​IMetric::metric_subtype ( ) const [inherited, pure virtual]
  Get the metric subtype.

  ###### Description

  Get the metric subtype

virtual MetricType NV::​Rules::​IMetric::metric_type ( ) const [inherited, pure virtual]
  Get the metric type.

  ###### Description

  Get the metric type

virtual const char* NV::​Rules::​IMetric::name ( ) [inherited, pure virtual]
  Get the metric name.

  ###### Description

  Get the metric name

virtual size_t NV::​Rules::​IMetric::num_instances ( ) [inherited, pure virtual]
  Get the number of instance values for this metric.

  ###### Description

  Get the number of instance values for this metric. Not all metrics have instance values. If a metric has instance values, it may also have correlation_ids matching these instance values.

virtual RollupOperation NV::​Rules::​IMetric::rollup_operation ( ) const [inherited, pure virtual]
  Get the type of rollup operation.

  ###### Description

  Get the type of rollup operation

virtual Unit NV::​Rules::​IMetric::unit ( ) const [inherited, pure virtual]
  Get the metric unit.

  ###### Description

  Get the metric unit

### 2.7. NV::Rules::INvtxDomainInfo Class Reference

### [NvRules Python garbage-collected classes.]

Represents a single NVTX domain of the NVTX state, including all ranges associated with this domain.

#### Public Member Functions

virtual std::​string name ( ) =0
  Get the domain name.
virtual INvtxRange* push_pop_range ( size_t idx ) =0
  Get a push/pop range object.
virtual std::​vector < std::​string > push_pop_ranges ( ) =0
  Get the list of push/pop range names.
virtual INvtxRange* start_end_range ( size_t idx ) =0
  Get a start/end range object.
virtual std::​vector < std::​string > start_end_ranges ( ) =0
  Get the list of start/end range names.

#### Member Functions

virtual std::​string NV::​Rules::​INvtxDomainInfo::name ( ) [inherited, pure virtual]
  Get the domain name.

  ###### Description

  Get the name of this domain

virtual INvtxRange* NV::​Rules::​INvtxDomainInfo::push_pop_range ( size_t idx ) [inherited, pure virtual]
  Get a push/pop range object.

  ###### Description

  Get a push/pop INvtxRange object by it's running index . The index is identical to the range's order on the call stack.

virtual std::​vector < std::​string > NV::​Rules::​INvtxDomainInfo::push_pop_ranges ( ) [inherited, pure virtual]
  Get the list of push/pop range names.

  ###### Description

  Get the sorted list of stacked push/pop range names in this domain, associated with the current INvtxState.

virtual INvtxRange* NV::​Rules::​INvtxDomainInfo::start_end_range ( size_t idx ) [inherited, pure virtual]
  Get a start/end range object.

  ###### Description

  Get a start/end INvtxRange object by it's running index .

virtual std::​vector < std::​string > NV::​Rules::​INvtxDomainInfo::start_end_ranges ( ) [inherited, pure virtual]
  Get the list of start/end range names.

  ###### Description

  Get the list of start/end range names in this domain, associated with the current INvtxState.

### 2.8. NV::Rules::INvtxRange Class Reference

### [NvRules Python garbage-collected classes.]

Represents a single NVTX Push/Pop or Start/End range.

#### Public Enumerations

enum PayloadType
  NVTX payload type.

#### Public Member Functions

virtual uint32_t category ( ) const =0
  Get the category attribute value.
virtual uint32_t color ( ) const =0
  Get the color attribute value.
virtual bool has_attributes ( ) const =0
  Check if the range has event attributes.
virtual std::​string message ( ) const =0
  Get the message attribute value.
virtual std::​string name ( ) const =0
  Get the range name.
virtual double payload_as_double ( ) const =0
  Get the payload attribute value as double (64-bit floating point).
virtual std::​string payload_as_string ( ) const =0
  Get the payload attribute value as a string.
virtual uint64_t payload_as_uint64 ( ) const =0
  Get the payload attribute value as uint64.
virtual PayloadType payload_type ( ) const =0
  Get the payload attribute type.

#### Enumerations

enum NV::​Rules::​INvtxRange::PayloadType [inherited]

  Type of an NVTX payload. This can be used to choose the appropriate payload_as_* function.

  ###### Values

  PAYLOAD_UNKNOWN
  PAYLOAD_UINT64
  PAYLOAD_INT64
  PAYLOAD_DOUBLE
  PAYLOAD_UINT32
  PAYLOAD_INT32
  PAYLOAD_FLOAT
  PAYLOAD_JSON

#### Member Functions

virtual uint32_t NV::​Rules::​INvtxRange::category ( ) const [inherited, pure virtual]
  Get the category attribute value.

  ###### Description

  Get the category attribute value. If INvtxRange::has_attributes returns false, the returned value is undefined.

virtual uint32_t NV::​Rules::​INvtxRange::color ( ) const [inherited, pure virtual]
  Get the color attribute value.

  ###### Description

  Get the color attribute value. If INvtxRange::has_attributes returns false, the returned value is undefined.

virtual bool NV::​Rules::​INvtxRange::has_attributes ( ) const [inherited, pure virtual]
  Check if the range has event attributes.

  ###### Description

  Check if the range has event attributes, such as INvtxRange::color, INvtxRange::category, or INvtxRange::message.

virtual std::​string NV::​Rules::​INvtxRange::message ( ) const [inherited, pure virtual]
  Get the message attribute value.

  ###### Description

  Get the message attribute value. If INvtxRange::has_attributes returns false, the returned value is undefined.

virtual std::​string NV::​Rules::​INvtxRange::name ( ) const [inherited, pure virtual]
  Get the range name.

  ###### Description

  Get the name of this range

virtual double NV::​Rules::​INvtxRange::payload_as_double ( ) const [inherited, pure virtual]
  Get the payload attribute value as double (64-bit floating point).

  ###### Description

  Get the payload attribute value as a double (64-bit floating point). If the INvtxRange::payload_type cannot be casted to double, the returned value is undefined. If INvtxRange::has_attributes returns false, the returned value is undefined.

virtual std::​string NV::​Rules::​INvtxRange::payload_as_string ( ) const [inherited, pure virtual]
  Get the payload attribute value as a string.

  ###### Description

  Get the payload attribute value as a string. If the INvtxRange::payload_type cannot be casted to a string, the returned value is undefined. If INvtxRange::has_attributes returns false, the returned value is undefined.

virtual uint64_t NV::​Rules::​INvtxRange::payload_as_uint64 ( ) const [inherited, pure virtual]
  Get the payload attribute value as uint64.

  ###### Description

  Get the payload attribute value as a uint64. If the INvtxRange::payload_type cannot be casted to uint64, the returned value is undefined. If INvtxRange::has_attributes returns false, the returned value is undefined.

virtual PayloadType NV::​Rules::​INvtxRange::payload_type ( ) const [inherited, pure virtual]
  Get the payload attribute type.

  ###### Description

  Get the payload attribute type. If INvtxRange::has_attributes returns false, the returned type is undefined.

### 2.9. NV::Rules::INvtxState Class Reference

### [NvRules Python garbage-collected classes.]

Represents the NVTX (Nvidia Tools Extensions) state associated with a single action.

#### Public Member Functions

virtual INvtxDomainInfo* domain_by_id ( long long unsigned id ) =0
  Get a domain by ID.
virtual std::​vector < long long unsigned > domains ( ) =0
  Get the domain IDs.

#### Member Functions

virtual INvtxDomainInfo* NV::​Rules::​INvtxState::domain_by_id ( long long unsigned id ) [inherited, pure virtual]
  Get a domain by ID.

  ###### Description

  Get a single domain info object by its ID. Use INvtxState::domains to retrieve the list of valid domain IDs.

virtual std::​vector < long long unsigned > NV::​Rules::​INvtxState::domains ( ) [inherited, pure virtual]
  Get the domain IDs.

  ###### Description

  Get the list of domain IDs in this state

### 2.10. NV::Rules::IRange Class Reference

### [NvRules Python garbage-collected classes.]

Represents a serial, ordered stream of execution, such as a CUDA stream. It holds one or more actions that were logically executing in this range

#### Public Member Functions

virtual IAction* action_by_idx ( size_t idx ) =0
  Get a single action by index.
virtual std::​set < long long unsigned > actions_by_nvtx ( const std::​vector < std::​string > & includes, const std::​vector < std::​string > & excludes ) =0
  Get a set of actions by their NVTX state.
virtual size_t num_actions ( ) =0
  Get the number of actions.

#### Member Functions

virtual IAction* NV::​Rules::​IRange::action_by_idx ( size_t idx ) [inherited, pure virtual]
  Get a single action by index.

  ###### Description

  Get a single IAction by index `idx`.

virtual std::​set < long long unsigned > NV::​Rules::​IRange::actions_by_nvtx ( const std::​vector < std::​string > & includes, const std::​vector < std::​string > & excludes ) [inherited, pure virtual]
  Get a set of actions by their NVTX state.

  ###### Description

  Get a set of indizes to IAction objects by their NVTX state. The state is defined using a series of `includes` and `excludes` .

virtual size_t NV::​Rules::​IRange::num_actions ( ) [inherited, pure virtual]
  Get the number of actions.

  ###### Description

  Get the number of available actions in this range

### 2.11. NV::Rules::ISourceInfo Class Reference

### [NvRules Python garbage-collected classes.]

Represents the source correlation info for a specific function address within an action

#### Public Member Functions

virtual const char* file_name ( ) =0
  Get the file name.
virtual uint32_t line ( ) =0
  Get the file line.

#### Member Functions

virtual const char* NV::​Rules::​ISourceInfo::file_name ( ) [inherited, pure virtual]
  Get the file name.

  ###### Description

  Get the file name, as embedded in the correlation info

virtual uint32_t NV::​Rules::​ISourceInfo::line ( ) [inherited, pure virtual]
  Get the file line.

  ###### Description

  Get the line within file_name