/include/cpustats/ThreadCpuUsage.h

  1/*
  2 * Copyright (C) 2011 The Android Open Source Project
  3 *
  4 * Licensed under the Apache License, Version 2.0 (the "License");
  5 * you may not use this file except in compliance with the License.
  6 * You may obtain a copy of the License at
  7 *
  8 *      http://www.apache.org/licenses/LICENSE-2.0
  9 *
 10 * Unless required by applicable law or agreed to in writing, software
 11 * distributed under the License is distributed on an "AS IS" BASIS,
 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 13 * See the License for the specific language governing permissions and
 14 * limitations under the License.
 15 */
 16
 17#ifndef _THREAD_CPU_USAGE_H
 18#define _THREAD_CPU_USAGE_H
 19
 20#include <cpustats/CentralTendencyStatistics.h>
 21
 22// Track CPU usage for the current thread, and maintain statistics on
 23// the CPU usage.  Units are in per-thread CPU ns, as reported by
 24// clock_gettime(CLOCK_THREAD_CPUTIME_ID).  Simple usage: for cyclic
 25// threads where you want to measure the execution time of the whole
 26// cycle, just call sampleAndEnable() at the start of each cycle.
 27// Then call statistics() to get the results, and resetStatistics()
 28// to start a new set of measurements.
 29// For acyclic threads, or for cyclic threads where you want to measure
 30// only part of each cycle, call enable(), disable(), and/or setEnabled()
 31// to demarcate the region(s) of interest, and then call sample() periodically.
 32// This class is not thread-safe for concurrent calls from multiple threads;
 33// the methods of this class may only be called by the current thread
 34// which constructed the object.
 35
 36class ThreadCpuUsage
 37{
 38
 39public:
 40    ThreadCpuUsage() :
 41        mIsEnabled(false),
 42        mWasEverEnabled(false),
 43        mAccumulator(0),
 44        // mPreviousTs
 45        // mMonotonicTs
 46        mMonotonicKnown(false)
 47        // mStatistics
 48        { }
 49
 50    ~ThreadCpuUsage() { }
 51
 52    // Return whether currently tracking CPU usage by current thread
 53    bool isEnabled()    { return mIsEnabled; }
 54
 55    // Enable tracking of CPU usage by current thread;
 56    // any CPU used from this point forward will be tracked.
 57    // Returns the previous enabled status.
 58    bool enable()       { return setEnabled(true); }
 59
 60    // Disable tracking of CPU usage by current thread;
 61    // any CPU used from this point forward will be ignored.
 62    // Returns the previous enabled status.
 63    bool disable()      { return setEnabled(false); }
 64
 65    // Set the enabled status and return the previous enabled status.
 66    // This method is intended to be used for safe nested enable/disabling.
 67    bool setEnabled(bool isEnabled);
 68
 69    // Add a sample point for central tendency statistics, and also
 70    // enable tracking if needed.  If tracking has never been enabled, then
 71    // enables tracking but does not add a sample (it is not possible to add
 72    // a sample the first time because no previous).  Otherwise if tracking is
 73    // enabled, then adds a sample for tracked CPU ns since the previous
 74    // sample, or since the first call to sampleAndEnable(), enable(), or
 75    // setEnabled(true).  If there was a previous sample but tracking is
 76    // now disabled, then adds a sample for the tracked CPU ns accumulated
 77    // up until the most recent disable(), resets this accumulator, and then
 78    // enables tracking.  Calling this method rather than enable() followed
 79    // by sample() avoids a race condition for the first sample.
 80    void sampleAndEnable();
 81
 82    // Add a sample point for central tendency statistics, but do not
 83    // change the tracking enabled status.  If tracking has either never been
 84    // enabled, or has never been enabled since the last sample, then log a warning
 85    // and don't add sample.  Otherwise, adds a sample for tracked CPU ns since
 86    // the previous sample or since the first call to sampleAndEnable(),
 87    // enable(), or setEnabled(true) if no previous sample.
 88    void sample();
 89
 90    // Return the elapsed delta wall clock ns since initial enable or statistics reset,
 91    // as reported by clock_gettime(CLOCK_MONOTONIC).
 92    long long elapsed() const;
 93
 94    // Reset statistics and elapsed.  Has no effect on tracking or accumulator.
 95    void resetStatistics();
 96
 97    // Return a const reference to the central tendency statistics.
 98    // Note that only the const methods can be called on this object.
 99    const CentralTendencyStatistics& statistics() const {
100        return mStatistics;
101    }
102
103private:
104    bool mIsEnabled;                // whether tracking is currently enabled
105    bool mWasEverEnabled;           // whether tracking was ever enabled
106    long long mAccumulator;         // accumulated thread CPU time since last sample, in ns
107    struct timespec mPreviousTs;    // most recent thread CPU time, valid only if mIsEnabled is true
108    struct timespec mMonotonicTs;   // most recent monotonic time
109    bool mMonotonicKnown;           // whether mMonotonicTs has been set
110    CentralTendencyStatistics mStatistics;
111};
112
113#endif //  _THREAD_CPU_USAGE_H