From eed6191370058e572a07ddf19b0b759dda2ff5e0 Mon Sep 17 00:00:00 2001
From: Pierre Pebay <pebay.pierre@gmail.com>
Date: Thu, 12 Dec 2024 17:40:22 +0100
Subject: [PATCH] #2302: perfData: Add doxygen comments

---
 src/vt/metrics/perf_data.h | 93 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 91 insertions(+), 2 deletions(-)

diff --git a/src/vt/metrics/perf_data.h b/src/vt/metrics/perf_data.h
index e1d956337c..197a73a6bc 100644
--- a/src/vt/metrics/perf_data.h
+++ b/src/vt/metrics/perf_data.h
@@ -66,36 +66,125 @@ namespace vt { namespace metrics {
 /**
  * \struct PerfData perf_data.h vt/metrics/perf_data.h
  *
- * \brief Tracks perf metrics per task
+ * \brief Tracks performance metrics per task
  *
+ * The PerfData component is responsible for initializing, tracking, and retrieving
+ * performance metrics for specific tasks using Linux performance counters.
  */
 struct PerfData: runtime::component::Component<PerfData>
 {
 public:
+  /**
+   * \brief Constructor for PerfData
+   *
+   * Initializes performance counters based on the \c VT_EVENTS environment variable,
+   * which is a comma seperated list of events available in the events header
+   * (example_events.h by default). For example: \c VT_EVENTS="cache-misses,instructions".
+   * If \c VT_EVENTS isn't set, will default to measuring instructions.
+   * Ensures only valid events are configured.
+   */
   PerfData();
+
+  /**
+   * \brief Destructor for PerfData
+   *
+   * Cleans up resources, closing file descriptors associated with performance
+   * counters.
+   */
   ~PerfData();
 
+  /**
+   * \brief Start performance measurement for a task
+   *
+   * Resets and enables the performance counters associated with the tracked events.
+   */
   void startTaskMeasurement();
+
+  /**
+   * \brief Stop performance measurement for a task
+   *
+   * Disables the performance counters associated with the tracked events.
+   */
   void stopTaskMeasurement();
+
+  /**
+   * \brief Get the measurements collected during the task execution
+   *
+   * Reads and retrieves the counter values for all tracked events.
+   *
+   * \return A map of event names to their corresponding measurement values.
+   *
+   * \throws vtAbort if there is a mismatch in data or an error during reading.
+   */
   std::unordered_map<std::string, uint64_t> getTaskMeasurements();
 
+  /**
+   * \brief Retrieve the current event map
+   *
+   * Returns the mapping of event names to their type and configuration values.
+   *
+   * \return A map of event names to pairs of event type and configuration values.
+   */
   std::unordered_map<std::string, std::pair<uint64_t,uint64_t>> getEventMap() const;
+
+  /**
+   * \brief Component startup method
+   */
   void startup() override;
+
+  /**
+   * \brief Get the component name
+   *
+   * \return The name of the component as a string.
+   */
   std::string name() override;
 
+  /**
+   * \brief Serialize the PerfData object
+   */
   template <typename SerializerT>
-  void PerfData::serialize(SerializerT& s) {
+  void serialize(SerializerT& s) {
     s | event_map_
       | event_names_
       | event_fds_;
   }
 
 private:
+  /**
+   * \brief Map of event names to event type and configuration
+   */
   std::unordered_map<std::string, std::pair<uint64_t,uint64_t>> event_map_;
+
+  /**
+   * \brief List of event names being tracked
+   */
   std::vector<std::string> event_names_;
+
+  /**
+   * \brief List of file descriptors associated with performance counters
+   */
   std::vector<int> event_fds_;
 
+  /**
+   * \brief Cleanup resources before aborting
+   *
+   * Closes any open file descriptors and clears internal data structures.
+   */
   void cleanupBeforeAbort();
+
+  /**
+   * \brief Open a performance counter event
+   *
+   * Wrapper around the syscall to open a performance counter.
+   *
+   * \param[in] hw_event The performance event attributes.
+   * \param[in] pid The process ID to measure (-1 for calling process).
+   * \param[in] cpu The CPU to measure (-1 for any CPU).
+   * \param[in] group_fd Group file descriptor for event grouping.
+   * \param[in] flags Additional flags for the syscall.
+   *
+   * \return The file descriptor for the event, or -1 on failure.
+   */
   static long perfEventOpen(struct perf_event_attr *hw_event, pid_t pid, int cpu, int group_fd, unsigned long flags);
 };