Update the doc of WallClockTimer with new tests

Based on crbug.com/166153, the base::TickClock still advances on Win and
Mac even when the device is suspended.

However, the WallClockTimer's doc claims that the TickClock always stop
during power suspension which is updated here.

We also add unit tests to make sure the WallClockTimer is able to cover
this case.

Bug: 1112516
Change-Id: I866a55c9b23c9460716fa6796c33fce5b62150cd
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2333041
Commit-Queue: Owen Min <zmin@chromium.org>
Reviewed-by: Greg Thompson <grt@chromium.org>
Cr-Commit-Position: refs/heads/master@{#795027}

base/util/timer/wall_clock_timer.h

@@ -27,8 +27,9 @@ namespace util {
 //
 // Comparison with OneShotTimer: WallClockTimer runs |user_task_| after |delay_|
 // expires according to usual time, while OneShotTimer runs |user_task_| after
-// |delay_| expires according to TimeTicks which freezes when power suspends
-// (desktop falls asleep).
+// |delay_| expires according to TimeTicks which may freeze on some platforms
+// when power suspends (desktop falls asleep). On platforms where TimeTicks
+// don't freeze, the WallClockTimer has the same behavior as OneShotTimer.
 //
 // The API is not thread safe. All methods must be called from the same
 // sequence (not necessarily the construction sequence), except for the

base/util/timer/wall_clock_timer_unittest.cc

@@ -216,4 +216,67 @@ TEST_F(WallClockTimerTest, DoubleStop) {
   ::testing::Mock::VerifyAndClearExpectations(&callback);
 }
 
+// On some platforms, TickClock will never freeze. WallClockTimer are still
+// supported on those platforms.
+TEST_F(WallClockTimerTest, NonStopTickClock) {
+  ::testing::StrictMock<base::MockOnceClosure> callback;
+  // Set up a WallClockTimer that will fire in one minute.
+  WallClockTimer wall_clock_timer(&clock_,
+                                  task_environment_.GetMockTickClock());
+  constexpr auto delay = base::TimeDelta::FromMinutes(1);
+  const auto start_time = base::Time::Now();
+  const auto run_time = start_time + delay;
+  clock_.SetNow(start_time);
+  wall_clock_timer.Start(FROM_HERE, run_time, callback.Get());
+  EXPECT_EQ(wall_clock_timer.desired_run_time(), start_time + delay);
+
+  // Pretend that time jumps forward 30 seconds while the machine is suspended.
+  constexpr auto past_time = base::TimeDelta::FromSeconds(30);
+
+  // Fastword with both clocks even the power is suspended.
+  mock_power_monitor_source_->Suspend();
+  clock_.SetNow(clock_.Now() + past_time);
+  task_environment_.FastForwardBy(past_time);
+  mock_power_monitor_source_->Resume();
+
+  // Ensure that the timer has not yet fired.
+  ::testing::Mock::VerifyAndClearExpectations(&callback);
+  EXPECT_EQ(wall_clock_timer.desired_run_time(), start_time + delay);
+
+  // Expect that the timer fires at the desired run time.
+  EXPECT_CALL(callback, Run());
+  // Both Time::Now() and |task_environment_| MockTickClock::Now()
+  // go forward by (|delay| - |past_time|):
+  FastForwardBy(delay - past_time);
+  ::testing::Mock::VerifyAndClearExpectations(&callback);
+  EXPECT_FALSE(wall_clock_timer.IsRunning());
+}
+
+TEST_F(WallClockTimerTest, NonStopTickClockWithLongPause) {
+  ::testing::StrictMock<base::MockOnceClosure> callback;
+  // Set up a WallClockTimer that will fire in one minute.
+  WallClockTimer wall_clock_timer(&clock_,
+                                  task_environment_.GetMockTickClock());
+  constexpr auto delay = base::TimeDelta::FromMinutes(1);
+  const auto start_time = base::Time::Now();
+  const auto run_time = start_time + delay;
+  clock_.SetNow(start_time);
+  wall_clock_timer.Start(FROM_HERE, run_time, callback.Get());
+  EXPECT_EQ(wall_clock_timer.desired_run_time(), start_time + delay);
+
+  // Pretend that time jumps forward 60 seconds while the machine is suspended.
+  constexpr auto past_time = base::TimeDelta::FromSeconds(60);
+
+  // Fastword with both clocks even the power is suspended. Timer fires at the
+  // moment of power resume.
+  EXPECT_CALL(callback, Run());
+  mock_power_monitor_source_->Suspend();
+  clock_.SetNow(clock_.Now() + past_time);
+  task_environment_.FastForwardBy(past_time);
+  mock_power_monitor_source_->Resume();
+
+  ::testing::Mock::VerifyAndClearExpectations(&callback);
+  EXPECT_FALSE(wall_clock_timer.IsRunning());
+}
+
 }  // namespace util