# NV::Rules::IAction

class IAction

  Action interface.

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

  Public Types

  enum class NameBase

    Basis for action names.

    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:

    enumerator FUNCTION
    enumerator DEMANGLED
    enumerator MANGLED

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

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

    Returns

      the new IMetric

  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.

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

    Returns

      the new IMetric

  virtual IMutableMetric *add_metric(const char *value_name) = 0

    Add a single mutable metric to this action.

    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.

    Returns

      the new IMutableMetric

  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.

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

    Returns

      the new IMetric

  virtual IMetric *metric_by_name(const char *metric_name) = 0

    Get a single metric by name.

    Get a single IMetric by `metric_name`

  virtual std::set<std::string> metric_names() = 0

    Get the set of metric names.

    Get the set of metrics available for this action

  virtual const char *name(NameBase base = NameBase::FUNCTION) = 0

    Get the action name.

    Get the action name

  virtual INvtxState *nvtx_state() = 0

    Get the NVTX state associated with this action.

    Returns

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

  virtual std::string ptx_by_pc(uint64_t address) = 0

    Get the PTX for a function address within this action.

    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.

    Returns

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

  virtual std::string sass_by_pc(uint64_t address) = 0

    Get the disassembled SASS for a function address within this action.

    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.

    Returns

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

  virtual std::map<std::string, std::string> source_files() = 0

    Get the source files associated with an action.

    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.

    Returns

      a map from file name to file content

  virtual ISourceInfo *source_info(uint64_t address) = 0

    Get the source info for a function address within this action.

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

    Returns

      a new ISourceInfo object if it is available

  inline virtual ~IAction()