-->
NvRules API (PDF) - v2021.2.2 (older) - Last updated September 2, 2021 - 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 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 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 ( ) =0
  Get the action name.
virtual INvtxState* nvtx_state ( ) =0
  Get the NVTX state associated with this action.
virtual ISourceInfo* source_info ( uint64_t address ) =0
  Get the source info for a function address within this action.

#### 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 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 ( ) [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 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 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 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 void require_metric ( const char* metric ) =0
virtual void require_rule ( const char* rule ) =0

#### Member Functions

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 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.

#### 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.

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.

### 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 Member Functions

virtual double as_double ( size_t instance ) =0
  Get a value from the metric list 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 list 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 list as 64bit integer.
virtual uint64_t as_uint64 ( ) =0
  Get the metric value as 64bit integer.
virtual bool has_value ( ValueKind value_kind ) =0
  Check if the metric has a value of a specific kind.
virtual ValueKind kind ( size_t instance ) =0
  Get the metric list entry value kind.
virtual ValueKind kind ( ) =0
  Get the metric value kind.
virtual const char* name ( ) =0
  Get the metric name.
virtual size_t num_instances ( ) =0
  Get the number of values in the metric list.

#### Member Functions

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

  ###### Description

  Get a value `instance` from the metric list 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 list as string.

  ###### Description

  Get a value `instance` from the metric list 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 list as 64bit integer.

  ###### Description

  Get a value `instance` from the metric list 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 bool NV::​Rules::​IMetric::has_value ( ValueKind value_kind ) [inherited, pure virtual]
  Check if the metric has a value of a specific kind.

  ###### Description

  Check if the metric has a value of a specific `value_kind`

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

  ###### Description

  Get the metric list entry value kind

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

  ###### Description

  Get the metric value kind

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 values in the metric list.

  ###### Description

  Get the number of values in the metric list

### 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 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.

#### 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