psh_utils: Update naming and add comments

Flag: EXEMPT refactor
Test: atest powerstats_collector_tests
Bug: 350114693
Change-Id: Iadfafab2282e902d0a887d1c5b9565748256b2b3
diff --git a/media/psh_utils/AudioToken.cpp b/media/psh_utils/AudioToken.cpp
index 626f959..f7bf382 100644
--- a/media/psh_utils/AudioToken.cpp
+++ b/media/psh_utils/AudioToken.cpp
@@ -41,6 +41,14 @@
     // APM has a back pointer to AudioToken, which is accessible on toString().
     // We first remove ourselves to prevent use after free.
     apm.clear_token_ptr(this);
+
+    // The client token is released when it is no longer registered with AudioFlinger.
+    // However, it is possible that AudioTrackTokens are still active when the client is released
+    // after crashing and some of its tracks are draining.  Those track tokens also
+    // maintain a pointer to the PowerClientStats keeping that consistent.
+
+    // Stopping the client moves its PowerClientStats from active to historical
+    // if it is the last pid associated with the client uid.
     apm.stopClient(mPid);
 }
 
diff --git a/media/psh_utils/PowerClientStats.cpp b/media/psh_utils/PowerClientStats.cpp
index 77d79e4..65f65a44 100644
--- a/media/psh_utils/PowerClientStats.cpp
+++ b/media/psh_utils/PowerClientStats.cpp
@@ -39,12 +39,12 @@
 void PowerClientStats::stop(int64_t actualNs) {
     std::lock_guard l(mMutex);
     if (--mTokenCount > 0) return;
-    if (mStartNs != 0) mDeltaNs += actualNs - mStartNs;
+    if (mStartNs != 0) mCumulativeNs += actualNs - mStartNs;
     mStartNs = 0;
     if (!mStartStats) return;
     const auto stopStats = PowerStatsCollector::getCollector().getStats(kStatTimeToleranceNs);
     if (stopStats && stopStats != mStartStats) {
-        *mDeltaStats += *stopStats - *mStartStats;
+        *mCumulativeStats += *stopStats - *mStartStats;
     }
     mStartStats.reset();
 }
@@ -64,15 +64,15 @@
     std::lock_guard l(mMutex);
 
     // Adjust delta time and stats if currently running.
-    auto deltaStats = mDeltaStats;
-    auto deltaNs = mDeltaNs;
-    if (mStartNs) deltaNs += systemTime(SYSTEM_TIME_BOOTTIME) - mStartNs;
+    auto cumulativeStats = mCumulativeStats;
+    auto cumulativeNs = mCumulativeNs;
+    if (mStartNs) cumulativeNs += systemTime(SYSTEM_TIME_BOOTTIME) - mStartNs;
     if (mStartStats) {
         const auto stopStats = PowerStatsCollector::getCollector().getStats(kStatTimeToleranceNs);
         if (stopStats && stopStats != mStartStats) {
-            auto newStats = std::make_shared<PowerStats>(*deltaStats);
+            auto newStats = std::make_shared<PowerStats>(*cumulativeStats);
             *newStats += *stopStats - *mStartStats;
-            deltaStats = newStats;
+            cumulativeStats = newStats;
         }
     }
 
@@ -81,7 +81,7 @@
             .append(std::to_string(mUid))
             .append(" ").append(mediautils::UidInfo::getInfo(mUid)->package)
             .append(" streams: ").append(std::to_string(mTokenCount))
-            .append(" seconds: ").append(std::to_string(deltaNs * 1e-9));
+            .append(" seconds: ").append(std::to_string(cumulativeNs * 1e-9));
     result.append(" {");
     for (auto pid : mPids) {
         result.append(" ").append(std::to_string(pid));
@@ -93,7 +93,7 @@
     if (stats) {
         std::string prefix2(prefix);
         prefix2.append("  ");
-        result.append("\n").append(deltaStats->normalizedEnergy(prefix2));
+        result.append("\n").append(cumulativeStats->normalizedEnergy(prefix2));
     }
     return result;
 }
diff --git a/media/psh_utils/include/psh_utils/PowerClientStats.h b/media/psh_utils/include/psh_utils/PowerClientStats.h
index 93d1fa9..6e27e41 100644
--- a/media/psh_utils/include/psh_utils/PowerClientStats.h
+++ b/media/psh_utils/include/psh_utils/PowerClientStats.h
@@ -87,10 +87,12 @@
     int64_t mStartNs GUARDED_BY(mMutex) = 0;
     std::shared_ptr<const PowerStats> mStartStats GUARDED_BY(mMutex);
 
-    // Total actual time app is active (stop - start)
-    int64_t mDeltaNs GUARDED_BY(mMutex) = 0;
-    // The stats taken for the active time (snapshots are quantized to 500ms accuracy).
-    std::shared_ptr<PowerStats> mDeltaStats GUARDED_BY(mMutex) = std::make_shared<PowerStats>();
+    // Cumulative time while active: sum of deltas of (stop - start).
+    int64_t mCumulativeNs GUARDED_BY(mMutex) = 0;
+    // Cumulative stats while active: sum of deltas of (stop - start),
+    // where snapshots are quantized to ~500ms accuracy.
+    std::shared_ptr<PowerStats> mCumulativeStats GUARDED_BY(mMutex) =
+            std::make_shared<PowerStats>();
 };
 
 } // namespace android::media::psh_utils