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

base/files/file.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef BASE_FILES_FILE_H_
 #define BASE_FILES_FILE_H_
 
 #include <stdint.h>
 
 #include <string>
@@ skipping 234 matching lines @@
   // Returns the current size of this file, or a negative number on failure.
   int64_t GetLength();
 
   // Truncates the file to the given length. If |length| is greater than the
   // current size of the file, the file is extended with zeros. If the file
   // doesn't exist, |false| is returned.
   bool SetLength(int64_t length);
 
   // 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.
   bool SetTimes(Time last_access_time, Time last_modified_time);
 
   // Returns some basic information for the given file.
   bool GetInfo(Info* info);
 
   // Attempts to take an exclusive write lock on the file. Returns immediately
   // (i.e. does not wait for another process to unlock the file). If the lock
@@ skipping 38 matching lines @@
   // Converts an error value to a human-readable form. Used for logging.
   static std::string ErrorToString(Error error);
 
  private:
   friend class FileTracing::ScopedTrace;
 
   // Creates or opens the given file. Only called if |path| has no
   // 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)
   win::ScopedHandle file_;
 #elif defined(OS_POSIX)
   ScopedFD file_;
 #endif
 
   // A path to use for tracing purposes. Set if file tracing is enabled during
   // |Initialize()|.
   FilePath tracing_path_;
 
   // Object tied to the lifetime of |this| that enables/disables tracing.
   FileTracing::ScopedEnabler trace_enabler_;
 
   Error error_details_;
   bool created_;
   bool async_;
 
   DISALLOW_COPY_AND_ASSIGN(File);
 };
 
 }  // namespace base
 
 #endif  // BASE_FILES_FILE_H_