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 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.
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 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 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 bool has_value ( ) =0
- Check if the metric has a non-instanced value.
- 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 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 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