michael@0: /* -*- Mode: C++; c-basic-offset: 2; indent-tabs-mode: nil; tab-width: 2; -*- */
michael@0: /* vim: set sw=4 ts=8 et tw=80 : */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #ifndef mozilla_dom_TaskThrottler_h
michael@0: #define mozilla_dom_TaskThrottler_h
michael@0: 
michael@0: #include <stdint.h>                     // for uint32_t
michael@0: #include "base/task.h"                  // for CancelableTask
michael@0: #include "mozilla/TimeStamp.h"          // for TimeDuration, TimeStamp
michael@0: #include "mozilla/RollingMean.h"        // for RollingMean
michael@0: #include "mozilla/mozalloc.h"           // for operator delete
michael@0: #include "nsAutoPtr.h"                  // for nsAutoPtr
michael@0: #include "nsTArray.h"                   // for nsTArray
michael@0: 
michael@0: namespace tracked_objects {
michael@0: class Location;
michael@0: }
michael@0: 
michael@0: namespace mozilla {
michael@0: namespace layers {
michael@0: 
michael@0: /** The TaskThrottler prevents update event overruns. It is used in cases where
michael@0:  * you're sending an async message and waiting for a reply. You need to call
michael@0:  * PostTask to queue a task and TaskComplete when you get a response.
michael@0:  *
michael@0:  * The call to TaskComplete will run the recent task posted since the last
michael@0:  * request was sent, if any. This means that at any time there can be at most 1
michael@0:  * outstanding request being processed and at most 1 queued behind it.
michael@0:  *
michael@0:  * This is used in the context of repainting a scrollable region. While another
michael@0:  * process is painting you might get several updates from the UI thread but when
michael@0:  * the paint is complete you want to send the most recent.
michael@0:  */
michael@0: 
michael@0: class TaskThrottler {
michael@0: public:
michael@0:   TaskThrottler(const TimeStamp& aTimeStamp);
michael@0: 
michael@0:   /** Post a task to be run as soon as there are no outstanding tasks.
michael@0:    *
michael@0:    * @param aLocation Use the macro FROM_HERE
michael@0:    * @param aTask     Ownership of this object is transferred to TaskThrottler
michael@0:    *                  which will delete it when it is either run or becomes
michael@0:    *                  obsolete or the TaskThrottler is destructed.
michael@0:    */
michael@0:   void PostTask(const tracked_objects::Location& aLocation,
michael@0:                 CancelableTask* aTask, const TimeStamp& aTimeStamp);
michael@0:   /**
michael@0:    * Mark the task as complete and process the next queued task.
michael@0:    */
michael@0:   void TaskComplete(const TimeStamp& aTimeStamp);
michael@0: 
michael@0:   /**
michael@0:    * Calculate the average time between processing the posted task and getting
michael@0:    * the TaskComplete() call back.
michael@0:    */
michael@0:   TimeDuration AverageDuration()
michael@0:   {
michael@0:     return mMean.empty() ? TimeDuration() : mMean.mean();
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * return true if Throttler has an outstanding task
michael@0:    */
michael@0:   bool IsOutstanding() { return mOutstanding; }
michael@0: 
michael@0:   /**
michael@0:    * Return the time elapsed since the last request was processed
michael@0:    */
michael@0:   TimeDuration TimeSinceLastRequest(const TimeStamp& aTimeStamp);
michael@0: 
michael@0:   /**
michael@0:    * Clear average history.
michael@0:    */
michael@0:   void ClearHistory() { mMean.clear(); }
michael@0: 
michael@0:   /**
michael@0:    * @param aMaxDurations The maximum number of durations to measure.
michael@0:    */
michael@0: 
michael@0:   void SetMaxDurations(uint32_t aMaxDurations)
michael@0:   {
michael@0:     if (aMaxDurations != mMean.maxValues()) {
michael@0:       mMean = RollingMean<TimeDuration, TimeDuration>(aMaxDurations);
michael@0:     }
michael@0:   }
michael@0: 
michael@0: private:
michael@0:   bool mOutstanding;
michael@0:   nsAutoPtr<CancelableTask> mQueuedTask;
michael@0:   TimeStamp mStartTime;
michael@0:   RollingMean<TimeDuration, TimeDuration> mMean;
michael@0: };
michael@0: 
michael@0: }
michael@0: }
michael@0: 
michael@0: #endif // mozilla_dom_TaskThrottler_h