/src/mozilla-central/widget/nsIdleService.h

Source (jump to first uncovered line)
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim:expandtab:shiftwidth=2:tabstop=2:
 */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef nsIdleService_h__
#define nsIdleService_h__

#include "nsIIdleServiceInternal.h"
#include "nsCOMPtr.h"
#include "nsITimer.h"
#include "nsTArray.h"
#include "nsIObserver.h"
#include "nsIIdleService.h"
#include "nsCategoryCache.h"
#include "nsWeakReference.h"
#include "mozilla/TimeStamp.h"

/**
 * Class we can use to store an observer with its associated idle time
 * requirement and whether or not the observer thinks it's "idle".
 */
class IdleListener {
public:
  nsCOMPtr<nsIObserver> observer;
  uint32_t reqIdleTime;
  bool isIdle;

  IdleListener(nsIObserver* obs, uint32_t reqIT, bool aIsIdle = false) :
    observer(obs), reqIdleTime(reqIT), isIdle(aIsIdle) {}
  ~IdleListener() {}
};

// This one will be declared later.
class nsIdleService;

/**
 * Class to handle the daily idle timer.
 */
class nsIdleServiceDaily : public nsIObserver,
                           public nsSupportsWeakReference
{
public:
  NS_DECL_ISUPPORTS
  NS_DECL_NSIOBSERVER

  explicit nsIdleServiceDaily(nsIIdleService* aIdleService);

  /**
   * Initializes the daily idle observer.
   * Keep this separated from the constructor, since it could cause pointer
   * corruption due to AddRef/Release of "this".
   */
  void Init();

private:
  virtual ~nsIdleServiceDaily();

  /**
   * StageIdleDaily is the interim call made when an idle-daily event is due.
   * However we don't want to fire idle-daily until the user is idle for this
   * session, so this sets up a short wait for an idle event which triggers
   * the actual idle-daily event.
   *
   * @param aHasBeenLongWait Pass true indicating nsIdleServiceDaily is having
   * trouble getting the idle-daily event fired. If true StageIdleDaily will
   * use a shorter idle wait time before firing idle-daily.
   */
  void StageIdleDaily(bool aHasBeenLongWait);

  /**
   * @note This is a normal pointer, part to avoid creating a cycle with the
   * idle service, part to avoid potential pointer corruption due to this class
   * being instantiated in the constructor of the service itself.
   */
  nsIIdleService* mIdleService;

  /**
   * Place to hold the timer used by this class to determine when a day has
   * passed, after that it will wait for idle time to be detected.
   */
  nsCOMPtr<nsITimer> mTimer;

  /**
   * Function that is called back once a day.
   */
  static void DailyCallback(nsITimer* aTimer, void* aClosure);

  /**
   * Cache of observers for the "idle-daily" category.
   */
  nsCategoryCache<nsIObserver> mCategoryObservers;

  /**
   * Boolean set to true when daily idle notifications should be disabled.
   */
  bool mShutdownInProgress;

  /**
   * Next time we expect an idle-daily timer to fire, in case timers aren't
   * very reliable on the platform. Value is in PR_Now microsecond units.
   */
  PRTime mExpectedTriggerTime;

  /**
   * Tracks which idle daily observer callback we ask for. There are two: a
   * regular long idle wait and a shorter wait if we've been waiting to fire
   * idle daily for an extended period. Set by StageIdleDaily.
   */
  int32_t mIdleDailyTriggerWait;
};

class nsIdleService : public nsIIdleServiceInternal
{
public:
  NS_DECL_ISUPPORTS
  NS_DECL_NSIIDLESERVICE
  NS_DECL_NSIIDLESERVICEINTERNAL

protected:
  static already_AddRefed<nsIdleService> GetInstance();

  nsIdleService();
  virtual ~nsIdleService();

  /**
   * If there is a platform specific function to poll the system idel time
   * then that must be returned in this function, and the function MUST return
   * true, otherwise then the function should be left unimplemented or made
   * to return false (this can also be used for systems where it depends on
   * the configuration of the system if the idle time can be determined)
   *
   * @param aIdleTime
   *        The idle time in ms.
   *
   * @return true if the idle time could be polled, false otherwise.
   *
   * @note The time returned by this function can be different than the one
   *       returned by GetIdleTime, as that is corrected by any calls to
   *       ResetIdleTimeOut(), unless you overwrite that function too...
   */
  virtual bool PollIdleTime(uint32_t* aIdleTime);

  /**
   * Function that determines if we are in poll mode or not.
   *
   * @return true if polling is supported, false otherwise.
   */
  virtual bool UsePollMode();

private:
  /**
   * Ensure that the timer is expiring at least at the given time
   *
   * The function might not restart the timer if there is one running currently
   *
   * @param aNextTimeout
   *        The last absolute time the timer should expire
   */
  void SetTimerExpiryIfBefore(mozilla::TimeStamp aNextTimeout);

  /**
   * Stores the next timeout time, 0 means timer not running
   */
  mozilla::TimeStamp mCurrentlySetToTimeoutAt;

  /**
   * mTimer holds the internal timer used by this class to detect when to poll
   * for idle time, when to check if idle timers should expire etc.
   */
  nsCOMPtr<nsITimer> mTimer;

  /**
   * Array of listeners that wants to be notified about idle time.
   */
  nsTArray<IdleListener> mArrayListeners;

  /**
   * Object keeping track of the daily idle thingy.
   */
  RefPtr<nsIdleServiceDaily> mDailyIdle;

  /**
   * Number of observers currently in idle mode.
   */
  uint32_t mIdleObserverCount;

  /**
   * Delta time from last non idle time to when the next observer should switch
   * to idle mode
   *
   * Time in seconds
   *
   * If this value is 0 it means there are no active observers
   */
  uint32_t mDeltaToNextIdleSwitchInS;

  /**
   * Absolute value for when the last user interaction took place.
   */
  mozilla::TimeStamp mLastUserInteraction;


  /**
   * Function that ensures the timer is running with at least the minimum time
   * needed.  It will kill the timer if there are no active observers.
   */
  void ReconfigureTimer(void);

  /**
   * Callback function that is called when the internal timer expires.
   *
   * This in turn calls the IdleTimerCallback that does the real processing
   */
  static void StaticIdleTimerCallback(nsITimer* aTimer, void* aClosure);

  /**
   * Function that handles when a timer has expired
   */
  void IdleTimerCallback(void);
};

#endif // nsIdleService_h__

Coverage Report

Created: 2018-09-25 14:53

Line	Count	Source (jump to first uncovered line)
1		/* -- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -- */
2		/* vim:expandtab:shiftwidth=2:tabstop=2:
3		*/
4		/* This Source Code Form is subject to the terms of the Mozilla Public
5		* License, v. 2.0. If a copy of the MPL was not distributed with this
6		* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7
8		#ifndef nsIdleService_h__
9		#define nsIdleService_h__
10
11		#include "nsIIdleServiceInternal.h"
12		#include "nsCOMPtr.h"
13		#include "nsITimer.h"
14		#include "nsTArray.h"
15		#include "nsIObserver.h"
16		#include "nsIIdleService.h"
17		#include "nsCategoryCache.h"
18		#include "nsWeakReference.h"
19		#include "mozilla/TimeStamp.h"
20
21		/**
22		* Class we can use to store an observer with its associated idle time
23		* requirement and whether or not the observer thinks it's "idle".
24		*/
25		class IdleListener {
26		public:
27		nsCOMPtr<nsIObserver> observer;
28		uint32_t reqIdleTime;
29		bool isIdle;
30
31		IdleListener(nsIObserver* obs, uint32_t reqIT, bool aIsIdle = false) :
32	0	observer(obs), reqIdleTime(reqIT), isIdle(aIsIdle) {}
33	0	~IdleListener() {}
34		};
35
36		// This one will be declared later.
37		class nsIdleService;
38
39		/**
40		* Class to handle the daily idle timer.
41		*/
42		class nsIdleServiceDaily : public nsIObserver,
43		public nsSupportsWeakReference
44		{
45		public:
46		NS_DECL_ISUPPORTS
47		NS_DECL_NSIOBSERVER
48
49		explicit nsIdleServiceDaily(nsIIdleService* aIdleService);
50
51		/**
52		* Initializes the daily idle observer.
53		* Keep this separated from the constructor, since it could cause pointer
54		* corruption due to AddRef/Release of "this".
55		*/
56		void Init();
57
58		private:
59		virtual ~nsIdleServiceDaily();
60
61		/**
62		* StageIdleDaily is the interim call made when an idle-daily event is due.
63		* However we don't want to fire idle-daily until the user is idle for this
64		* session, so this sets up a short wait for an idle event which triggers
65		* the actual idle-daily event.
66		*
67		* @param aHasBeenLongWait Pass true indicating nsIdleServiceDaily is having
68		* trouble getting the idle-daily event fired. If true StageIdleDaily will
69		* use a shorter idle wait time before firing idle-daily.
70		*/
71		void StageIdleDaily(bool aHasBeenLongWait);
72
73		/**
74		* @note This is a normal pointer, part to avoid creating a cycle with the
75		* idle service, part to avoid potential pointer corruption due to this class
76		* being instantiated in the constructor of the service itself.
77		*/
78		nsIIdleService* mIdleService;
79
80		/**
81		* Place to hold the timer used by this class to determine when a day has
82		* passed, after that it will wait for idle time to be detected.
83		*/
84		nsCOMPtr<nsITimer> mTimer;
85
86		/**
87		* Function that is called back once a day.
88		*/
89		static void DailyCallback(nsITimer* aTimer, void* aClosure);
90
91		/**
92		* Cache of observers for the "idle-daily" category.
93		*/
94		nsCategoryCache<nsIObserver> mCategoryObservers;
95
96		/**
97		* Boolean set to true when daily idle notifications should be disabled.
98		*/
99		bool mShutdownInProgress;
100
101		/**
102		* Next time we expect an idle-daily timer to fire, in case timers aren't
103		* very reliable on the platform. Value is in PR_Now microsecond units.
104		*/
105		PRTime mExpectedTriggerTime;
106
107		/**
108		* Tracks which idle daily observer callback we ask for. There are two: a
109		* regular long idle wait and a shorter wait if we've been waiting to fire
110		* idle daily for an extended period. Set by StageIdleDaily.
111		*/
112		int32_t mIdleDailyTriggerWait;
113		};
114
115		class nsIdleService : public nsIIdleServiceInternal
116		{
117		public:
118		NS_DECL_ISUPPORTS
119		NS_DECL_NSIIDLESERVICE
120		NS_DECL_NSIIDLESERVICEINTERNAL
121
122		protected:
123		static already_AddRefed<nsIdleService> GetInstance();
124
125		nsIdleService();
126		virtual ~nsIdleService();
127
128		/**
129		* If there is a platform specific function to poll the system idel time
130		* then that must be returned in this function, and the function MUST return
131		* true, otherwise then the function should be left unimplemented or made
132		* to return false (this can also be used for systems where it depends on
133		* the configuration of the system if the idle time can be determined)
134		*
135		* @param aIdleTime
136		* The idle time in ms.
137		*
138		* @return true if the idle time could be polled, false otherwise.
139		*
140		* @note The time returned by this function can be different than the one
141		* returned by GetIdleTime, as that is corrected by any calls to
142		* ResetIdleTimeOut(), unless you overwrite that function too...
143		*/
144		virtual bool PollIdleTime(uint32_t* aIdleTime);
145
146		/**
147		* Function that determines if we are in poll mode or not.
148		*
149		* @return true if polling is supported, false otherwise.
150		*/
151		virtual bool UsePollMode();
152
153		private:
154		/**
155		* Ensure that the timer is expiring at least at the given time
156		*
157		* The function might not restart the timer if there is one running currently
158		*
159		* @param aNextTimeout
160		* The last absolute time the timer should expire
161		*/
162		void SetTimerExpiryIfBefore(mozilla::TimeStamp aNextTimeout);
163
164		/**
165		* Stores the next timeout time, 0 means timer not running
166		*/
167		mozilla::TimeStamp mCurrentlySetToTimeoutAt;
168
169		/**
170		* mTimer holds the internal timer used by this class to detect when to poll
171		* for idle time, when to check if idle timers should expire etc.
172		*/
173		nsCOMPtr<nsITimer> mTimer;
174
175		/**
176		* Array of listeners that wants to be notified about idle time.
177		*/
178		nsTArray<IdleListener> mArrayListeners;
179
180		/**
181		* Object keeping track of the daily idle thingy.
182		*/
183		RefPtr<nsIdleServiceDaily> mDailyIdle;
184
185		/**
186		* Number of observers currently in idle mode.
187		*/
188		uint32_t mIdleObserverCount;
189
190		/**
191		* Delta time from last non idle time to when the next observer should switch
192		* to idle mode
193		*
194		* Time in seconds
195		*
196		* If this value is 0 it means there are no active observers
197		*/
198		uint32_t mDeltaToNextIdleSwitchInS;
199
200		/**
201		* Absolute value for when the last user interaction took place.
202		*/
203		mozilla::TimeStamp mLastUserInteraction;
204
205
206		/**
207		* Function that ensures the timer is running with at least the minimum time
208		* needed. It will kill the timer if there are no active observers.
209		*/
210		void ReconfigureTimer(void);
211
212		/**
213		* Callback function that is called when the internal timer expires.
214		*
215		* This in turn calls the IdleTimerCallback that does the real processing
216		*/
217		static void StaticIdleTimerCallback(nsITimer* aTimer, void* aClosure);
218
219		/**
220		* Function that handles when a timer has expired
221		*/
222		void IdleTimerCallback(void);
223		};
224
225		#endif // nsIdleService_h__