feat: Add ScopedPauseTiming RAII helper

Adds a new `benchmark::ScopedPauseTiming` class that provides a convenient
RAII-style mechanism for pausing and resuming benchmark timers.

This is less error-prone than manually calling `PauseTiming` and
`ResumeTiming`, as it guarantees that the timer is resumed when the
scope is exited.

- Added `ScopedPauseTiming` to `include/benchmark/state.h`.
- Added a new test `test/scoped_pause_test.cc` to verify the
  functionality and prevent regressions.
- Updated `test/CMakeLists.txt` to include the new test.
- Added documentation for the new feature in `docs/user_guide.md`.

Author: dmah42

docs/user_guide.md

@@ -1066,6 +1066,29 @@ BENCHMARK(BM_SetInsert_With_Timer_Control)->Ranges({{1<<10, 8<<10}, {128, 512}})
 ```
 <!-- {% endraw %} -->
 
+For convenience, a `ScopedPauseTiming` class is provided to manage pausing and
+resuming timers within a scope. This is less error-prone than manually calling
+`PauseTiming` and `ResumeTiming`.
+
+<!-- {% raw %} -->
+```c++
+static void BM_SetInsert_With_Scoped_Timer_Control(benchmark::State& state) {
+  std::set<int> data;
+  for (auto _ : state) {
+    {
+      benchmark::ScopedPauseTiming pause(state); // Pauses timing
+      data = ConstructRandomSet(state.range(0));
+    } // Timing resumes automatically when 'pause' goes out of scope
+
+    // The rest will be measured.
+    for (int j = 0; j < state.range(1); ++j)
+      data.insert(RandomNumber());
+  }
+}
+BENCHMARK(BM_SetInsert_With_Scoped_Timer_Control)->Ranges({{1<<10, 8<<10}, {128, 512}});
+```
+<!-- {% endraw %} -->
+
 <a name="manual-timing" />
 
 ## Manual Timing

include/benchmark/state.h

@@ -256,6 +256,19 @@ inline BENCHMARK_ALWAYS_INLINE State::StateIterator State::end() {
   return StateIterator();
 }
 
+class ScopedPauseTiming {
+ public:
+  explicit ScopedPauseTiming(State& state) : state_(state) {
+    state_.PauseTiming();
+  }
+  ~ScopedPauseTiming() { state_.ResumeTiming(); }
+
+ private:
+  ScopedPauseTiming(const ScopedPauseTiming&) = delete;
+  void operator=(const ScopedPauseTiming&) = delete;
+  State& state_;
+};
+
 }  // namespace benchmark
 
 #if defined(_MSC_VER)

test/CMakeLists.txt

@@ -225,6 +225,9 @@ benchmark_add_test(NAME complexity_benchmark COMMAND complexity_test --benchmark
 compile_output_test(locale_impermeability_test)
 benchmark_add_test(NAME locale_impermeability_test COMMAND locale_impermeability_test)
 
+compile_output_test(scoped_pause_test)
+benchmark_add_test(NAME scoped_pause_test COMMAND scoped_pause_test)
+
 ###############################################################################
 # GoogleTest Unit Tests
 ###############################################################################

test/scoped_pause_test.cc

@@ -0,0 +1,29 @@
+
+#include <chrono>
+#include <thread>
+
+#include "benchmark/benchmark.h"
+#include "output_test.h"
+
+// BM_ScopedPause sleeps for 10ms in a ScopedPauseTiming block.
+// The reported time should be much less than 10ms.
+void BM_ScopedPause(benchmark::State& state) {
+  for (auto _ : state) {
+    benchmark::ScopedPauseTiming pause(state);
+    std::this_thread::sleep_for(std::chrono::milliseconds(10));
+  }
+}
+BENCHMARK(BM_ScopedPause)->UseRealTime()->Iterations(1);
+
+void CheckResults(Results const& results) {
+  // Check that the real time is much less than the 10ms sleep time.
+  // Allow for up to 1ms of timing noise/overhead.
+  CHECK_FLOAT_RESULT_VALUE(results, "real_time", LT, 1e6, 0.0);
+}
+CHECK_BENCHMARK_RESULTS("BM_ScopedPause", &CheckResults);
+
+int main(int argc, char* argv[]) {
+  benchmark::MaybeReenterWithoutASLR(argc, argv);
+  RunOutputTests(argc, argv);
+  return 0;
+}