important_file_writer.h 9.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224
  1. // Copyright (c) 2012 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef BASE_FILES_IMPORTANT_FILE_WRITER_H_
  5. #define BASE_FILES_IMPORTANT_FILE_WRITER_H_
  6. #include <memory>
  7. #include <string>
  8. #include "base/base_export.h"
  9. #include "base/callback.h"
  10. #include "base/files/file_path.h"
  11. #include "base/memory/raw_ptr.h"
  12. #include "base/sequence_checker.h"
  13. #include "base/strings/string_piece.h"
  14. #include "base/time/time.h"
  15. #include "base/timer/timer.h"
  16. #include "third_party/abseil-cpp/absl/types/variant.h"
  17. namespace base {
  18. class SequencedTaskRunner;
  19. // Helper for atomically writing a file to ensure that it won't be corrupted by
  20. // *application* crash during write (implemented as create, flush, rename).
  21. //
  22. // As an added benefit, ImportantFileWriter makes it less likely that the file
  23. // is corrupted by *system* crash, though even if the ImportantFileWriter call
  24. // has already returned at the time of the crash it is not specified which
  25. // version of the file (old or new) is preserved. And depending on system
  26. // configuration (hardware and software) a significant likelihood of file
  27. // corruption may remain, thus using ImportantFileWriter is not a valid
  28. // substitute for file integrity checks and recovery codepaths for malformed
  29. // files.
  30. //
  31. // Also note that ImportantFileWriter can be *really* slow (cf. File::Flush()
  32. // for details) and thus please don't block shutdown on ImportantFileWriter.
  33. class BASE_EXPORT ImportantFileWriter {
  34. public:
  35. // Promise-like callback that returns (via output parameter) the serialized
  36. // data to be written. This callback is invoked on the sequence where I/O
  37. // operations are executed. Returning false indicates an error.
  38. using BackgroundDataProducerCallback = base::OnceCallback<bool(std::string*)>;
  39. // Used by ScheduleSave to lazily provide the data to be saved. Allows us
  40. // to also batch data serializations.
  41. class BASE_EXPORT DataSerializer {
  42. public:
  43. // Should put serialized string in |data| and return true on successful
  44. // serialization. Will be called on the same thread on which
  45. // ImportantFileWriter has been created.
  46. virtual bool SerializeData(std::string* data) = 0;
  47. protected:
  48. virtual ~DataSerializer() = default;
  49. };
  50. // Same as DataSerializer but allows the caller to move some of the
  51. // serialization logic to the sequence where I/O operations are executed.
  52. class BASE_EXPORT BackgroundDataSerializer {
  53. public:
  54. // Returns a promise-like callback that, when invoked, will produce the
  55. // serialized string. This getter itself will be called on the same thread
  56. // on which ImportantFileWriter has been created, but the callback will be
  57. // invoked from the sequence where I/O operations are executed.
  58. virtual BackgroundDataProducerCallback
  59. GetSerializedDataProducerForBackgroundSequence() = 0;
  60. protected:
  61. virtual ~BackgroundDataSerializer() = default;
  62. };
  63. // Save |data| to |path| in an atomic manner. Blocks and writes data on the
  64. // current thread. Does not guarantee file integrity across system crash (see
  65. // the class comment above).
  66. static bool WriteFileAtomically(const FilePath& path,
  67. StringPiece data,
  68. StringPiece histogram_suffix = StringPiece());
  69. // Initialize the writer.
  70. // |path| is the name of file to write.
  71. // |task_runner| is the SequencedTaskRunner instance where on which we will
  72. // execute file I/O operations.
  73. // All non-const methods, ctor and dtor must be called on the same thread.
  74. ImportantFileWriter(const FilePath& path,
  75. scoped_refptr<SequencedTaskRunner> task_runner,
  76. StringPiece histogram_suffix = StringPiece());
  77. // Same as above, but with a custom commit interval.
  78. ImportantFileWriter(const FilePath& path,
  79. scoped_refptr<SequencedTaskRunner> task_runner,
  80. TimeDelta interval,
  81. StringPiece histogram_suffix = StringPiece());
  82. ImportantFileWriter(const ImportantFileWriter&) = delete;
  83. ImportantFileWriter& operator=(const ImportantFileWriter&) = delete;
  84. // You have to ensure that there are no pending writes at the moment
  85. // of destruction.
  86. ~ImportantFileWriter();
  87. const FilePath& path() const { return path_; }
  88. // Returns true if there is a scheduled write pending which has not yet
  89. // been started.
  90. bool HasPendingWrite() const;
  91. // Save |data| to target filename. Does not block. If there is a pending write
  92. // scheduled by ScheduleWrite(), it is cancelled.
  93. void WriteNow(std::unique_ptr<std::string> data);
  94. // Schedule a save to target filename. Data will be serialized and saved
  95. // to disk after the commit interval. If another ScheduleWrite is issued
  96. // before that, only one serialization and write to disk will happen, and
  97. // the most recent |serializer| will be used. This operation does not block.
  98. // |serializer| should remain valid through the lifetime of
  99. // ImportantFileWriter.
  100. void ScheduleWrite(DataSerializer* serializer);
  101. // Same as above but uses the BackgroundDataSerializer API.
  102. void ScheduleWriteWithBackgroundDataSerializer(
  103. BackgroundDataSerializer* serializer);
  104. // Serialize data pending to be saved and execute write on background thread.
  105. void DoScheduledWrite();
  106. // Registers |before_next_write_callback| and |after_next_write_callback| to
  107. // be synchronously invoked from WriteFileAtomically() before its next write
  108. // and after its next write, respectively. The boolean passed to
  109. // |after_next_write_callback| indicates whether the write was successful.
  110. // Both callbacks must be thread safe as they will be called on |task_runner_|
  111. // and may be called during Chrome shutdown.
  112. // If called more than once before a write is scheduled on |task_runner|, the
  113. // latest callbacks clobber the others.
  114. void RegisterOnNextWriteCallbacks(
  115. OnceClosure before_next_write_callback,
  116. OnceCallback<void(bool success)> after_next_write_callback);
  117. TimeDelta commit_interval() const {
  118. return commit_interval_;
  119. }
  120. // Overrides the timer to use for scheduling writes with |timer_override|.
  121. void SetTimerForTesting(OneShotTimer* timer_override);
  122. #if defined(UNIT_TEST)
  123. size_t previous_data_size() const { return previous_data_size_; }
  124. #endif
  125. void set_previous_data_size(size_t previous_data_size) {
  126. previous_data_size_ = previous_data_size;
  127. }
  128. private:
  129. const OneShotTimer& timer() const {
  130. return timer_override_ ? *timer_override_ : timer_;
  131. }
  132. OneShotTimer& timer() { return timer_override_ ? *timer_override_ : timer_; }
  133. // Same as WriteNow() but it uses a promise-like signature that allows running
  134. // custom logic in the background sequence.
  135. void WriteNowWithBackgroundDataProducer(
  136. BackgroundDataProducerCallback background_producer);
  137. // Helper function to call WriteFileAtomically() with a promise-like callback
  138. // producing a std::string.
  139. static void ProduceAndWriteStringToFileAtomically(
  140. const FilePath& path,
  141. BackgroundDataProducerCallback data_producer_for_background_sequence,
  142. OnceClosure before_write_callback,
  143. OnceCallback<void(bool success)> after_write_callback,
  144. const std::string& histogram_suffix);
  145. // Writes |data| to |path|, recording histograms with an optional
  146. // |histogram_suffix|. |from_instance| indicates whether the call originates
  147. // from an instance of ImportantFileWriter or a direct call to
  148. // WriteFileAtomically. When false, the directory containing |path| is added
  149. // to the set cleaned by the ImportantFileWriterCleaner (Windows only).
  150. static bool WriteFileAtomicallyImpl(const FilePath& path,
  151. StringPiece data,
  152. StringPiece histogram_suffix,
  153. bool from_instance);
  154. void ClearPendingWrite();
  155. // Invoked synchronously on the next write event.
  156. OnceClosure before_next_write_callback_;
  157. OnceCallback<void(bool success)> after_next_write_callback_;
  158. // Path being written to.
  159. const FilePath path_;
  160. // TaskRunner for the thread on which file I/O can be done.
  161. const scoped_refptr<SequencedTaskRunner> task_runner_;
  162. // Timer used to schedule commit after ScheduleWrite.
  163. OneShotTimer timer_;
  164. // An override for |timer_| used for testing.
  165. raw_ptr<OneShotTimer> timer_override_ = nullptr;
  166. // Serializer which will provide the data to be saved.
  167. absl::variant<absl::monostate, DataSerializer*, BackgroundDataSerializer*>
  168. serializer_;
  169. // Time delta after which scheduled data will be written to disk.
  170. const TimeDelta commit_interval_;
  171. // Custom histogram suffix.
  172. const std::string histogram_suffix_;
  173. // Memorizes the amount of data written on the previous write. This helps
  174. // preallocating memory for the data serialization. It is only used for
  175. // scheduled writes.
  176. size_t previous_data_size_ = 0;
  177. SEQUENCE_CHECKER(sequence_checker_);
  178. WeakPtrFactory<ImportantFileWriter> weak_factory_{this};
  179. };
  180. } // namespace base
  181. #endif // BASE_FILES_IMPORTANT_FILE_WRITER_H_