From c7ab1b987ba9badeda367145b2e2073fc0ed0d57 Mon Sep 17 00:00:00 2001
From: Eli Bendersky <eliben@gmail.com>
Date: Wed, 30 Dec 2015 06:01:19 -0800
Subject: [PATCH] Update README to mention UseRealTime for wallclock time
 measurements.

Also adding a use case in the API header.

Fixes #170
---
 README.md                         | 17 ++++++++++++++---
 include/benchmark/benchmark_api.h | 10 +++++-----
 2 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 8c656ead..1fa7186e 100644
--- a/README.md
+++ b/README.md
@@ -145,9 +145,10 @@ Three macros are provided for adding benchmark templates.
 #define BENCHMARK_TEMPLATE2(func, arg1, arg2)
 ```
 
-In a multithreaded test, it is guaranteed that none of the threads will start
-until all have called KeepRunning, and all will have finished before KeepRunning
-returns false. As such, any global setup or teardown you want to do can be
+In a multithreaded test (benchmark invoked by multiple threads simultaneously),
+it is guaranteed that none of the threads will start until all have called
+KeepRunning, and all will have finished before KeepRunning returns false. As
+such, any global setup or teardown you want to do can be
 wrapped in a check against the thread index:
 
 ```c++
@@ -165,6 +166,16 @@ static void BM_MultiThreaded(benchmark::State& state) {
 BENCHMARK(BM_MultiThreaded)->Threads(2);
 ```
 
+If the benchmarked code itself uses threads and you want to compare it to
+single-threaded code, you may want to use real-time ("wallclock") measurements
+for latency comparisons:
+
+```c++
+BENCHMARK(BM_test)->Range(8, 8<<10)->UseRealTime();
+```
+
+Without `UseRealTime`, CPU time is used by default.
+
 To prevent a value or expression from being optimized away by the compiler
 the `benchmark::DoNotOptimize(...)` function can be used.
 
diff --git a/include/benchmark/benchmark_api.h b/include/benchmark/benchmark_api.h
index 4dec01fc..55235878 100644
--- a/include/benchmark/benchmark_api.h
+++ b/include/benchmark/benchmark_api.h
@@ -417,11 +417,11 @@ public:
   // option overrides the `benchmark_min_time` flag.
   Benchmark* MinTime(double t);
 
-  // If a particular benchmark is I/O bound, or if for some reason CPU
-  // timings are not representative, call this method. If called, the elapsed
-  // time will be used to control how many iterations are run, and in the
-  // printing of items/second or MB/seconds values.  If not called, the cpu
-  // time used by the benchmark will be used.
+  // If a particular benchmark is I/O bound, runs multiple threads internally or
+  // if for some reason CPU timings are not representative, call this method. If
+  // called, the elapsed time will be used to control how many iterations are
+  // run, and in the printing of items/second or MB/seconds values.  If not
+  // called, the cpu time used by the benchmark will be used.
   Benchmark* UseRealTime();
 
   // Support for running multiple copies of the same benchmark concurrently