Add some words of caution to File::Flush().

Document latency percentiles.

BUG=473337

Review-Url: https://codereview.chromium.org/2171833002
Cr-Commit-Position: refs/heads/master@{#407305}

base/files/file.cc

@@ -138,12 +138,4 @@ std::string File::ErrorToString(Error error) {
   return "";
 }
 
-bool File::Flush() {
-  ElapsedTimer timer;
-  SCOPED_FILE_TRACE("Flush");
-  bool return_value = DoFlush();
-  UMA_HISTOGRAM_TIMES("PlatformFile.FlushTime", timer.Elapsed());
-  return return_value;
-}
-
 }  // namespace base

base/files/file.h

@@ -252,6 +252,16 @@ class BASE_EXPORT File {
 
   // Instructs the filesystem to flush the file to disk. (POSIX: fsync, Windows:
   // FlushFileBuffers).
+  // Calling Flush() does not guarantee file integrity and thus is not a valid
+  // substitute for file integrity checks and recovery codepaths for malformed
+  // files. It can also be *really* slow, so avoid blocking on Flush(),
+  // especially please don't block shutdown on Flush().
+  // Latency percentiles of Flush() across all platforms as of July 2016:
+  // 50 %     > 5 ms
+  // 10 %     > 58 ms
+  //  1 %     > 357 ms
+  //  0.1 %   > 1.8 seconds
+  //  0.01 %  > 7.6 seconds
   bool Flush();
 
   // Updates the file times.
@@ -310,10 +320,6 @@ class BASE_EXPORT File {
   // traversal ('..') components.
   void DoInitialize(const FilePath& path, uint32_t flags);
 
-  // TODO(tnagel): Reintegrate into Flush() once histogram isn't needed anymore,
-  // cf. issue 473337.
-  bool DoFlush();
-
   void SetPlatformFile(PlatformFile file);
 
 #if defined(OS_WIN)

base/files/file_posix.cc

@@ -511,9 +511,10 @@ void File::DoInitialize(const FilePath& path, uint32_t flags) {
 }
 #endif  // !defined(OS_NACL)
 
-bool File::DoFlush() {
+bool File::Flush() {
   ThreadRestrictions::AssertIOAllowed();
   DCHECK(IsValid());
+  SCOPED_FILE_TRACE("Flush");
 
 #if defined(OS_NACL)
   NOTIMPLEMENTED();  // NaCl doesn't implement fsync.

base/files/file_win.cc

@@ -396,9 +396,10 @@ void File::DoInitialize(const FilePath& path, uint32_t flags) {
   }
 }
 
-bool File::DoFlush() {
+bool File::Flush() {
   ThreadRestrictions::AssertIOAllowed();
   DCHECK(IsValid());
+  SCOPED_FILE_TRACE("Flush");
   return ::FlushFileBuffers(file_.Get()) != FALSE;
 }
 

tools/metrics/histograms/histograms.xml

@@ -40975,6 +40975,10 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
 </histogram>
 
 <histogram name="PlatformFile.FlushTime" units="ms">
+  <obsolete>
+    Deprecated as of 2016-07 because the histogram's purpose of adding colour to
+    the description of File::Flush() has been fulfilled.
+  </obsolete>
   <owner>tnagel@chromium.org</owner>
   <summary>The time it takes to run File::Flush().</summary>
 </histogram>