# NV::Rules::IFrontend

class IFrontend

  Frontend interface.

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

  Public Types

  using Dict = std::map<std::string, double>
  enum class MarkerKind

    Marker Kind.

    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:

    enumerator SASS
    enumerator SOURCE
  enum class MsgType

    Message type.

    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:

    enumerator MSG_NONE
    enumerator MSG_OK
    enumerator MSG_OPTIMIZATION
    enumerator MSG_WARNING
    enumerator MSG_ERROR
  using RuleId = std::string
  enum class Severity

    Focus metric severity.

    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:

    enumerator SEVERITY_DEFAULT
    enumerator SEVERITY_LOW
    enumerator SEVERITY_HIGH
  enum class SpeedupType

    Speedup estimation type.

    The type of speedup estimation used when calling speedup. `LOCAL` The proportional increase in efficiency of the hardware usage when viewing the performance problem in isolation. `GLOBAL` The proportional reduction in runtime of the entire workload.

    Values:

    enumerator LOCAL
    enumerator GLOBAL

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

    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 load_chart_from_file(const char *filename) = 0

    Load a ProfilerSection google protcol buffer chart from `filename`.

  virtual int message(const char *str, const char *name = nullptr) = 0

    Rule result message.

    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 int message(MsgType type, const char *str, const char *name = nullptr) = 0

    Rule result message.

    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 Dict receive_dict_from_parent(const RuleId &parent_id) = 0

    Receive a dictionary from parent rule `parent_id`.

    Receive a dictionary of type dict[str,float] sent using `send_dict_to_children` . In case `parent_id` does not represent a pre-specified parent rule of this rule, or in case the parent rule has not been executed, an empty dict will be returned.

  virtual void send_dict_to_children(const Dict &dict) = 0

    Send a dictionary `dict` to all child rules.

    Sends a Python dictionary of type dict[str,float] to all rules that specify this rule as a parent rule. Child rules can retrieve the message using `receive_dict_from_parent` . In case this function is called repeatedly, the dict is updated accordingly, thereby adding new key-value pairs, and overwriting values of pre-existing keys.

  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.

    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 source_marker(const char *str, uint64_t address_or_line, MarkerKind kind, MsgType type = MsgType::MSG_NONE) = 0

    Rule source marker.

    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 speedup(int message_id, SpeedupType type, double estimated_speedup) = 0

    Rule estimated speedup message.

    Issues an estimated speedup to the frontend associated to the message with ID `message_id` . When `type` is `SpeedupType::GLOBAL`, it indicates what proportional decrease in workload runtime could potentially be achieved, when following the guidelines of the rule. When `type` is `SpeedupType::LOCAL`, it indicates what increase in the efficiency of the hardware usage within the context of the performance problem could be achieved. Returns whether the speedup could be set successfully for the `message_id` .

  inline virtual ~IFrontend()