file_path_watcher.h 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137
  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. // This module provides a way to monitor a file or directory for changes.
  5. #ifndef BASE_FILES_FILE_PATH_WATCHER_H_
  6. #define BASE_FILES_FILE_PATH_WATCHER_H_
  7. #include <memory>
  8. #include <utility>
  9. #include "base/base_export.h"
  10. #include "base/callback_forward.h"
  11. #include "base/memory/scoped_refptr.h"
  12. #include "base/sequence_checker.h"
  13. #include "base/task/sequenced_task_runner.h"
  14. #include "build/build_config.h"
  15. namespace base {
  16. class FilePath;
  17. // This class lets you register interest in changes on a FilePath.
  18. // The callback will get called whenever the file or directory referenced by the
  19. // FilePath is changed, including created or deleted. Due to limitations in the
  20. // underlying OS APIs, FilePathWatcher has slightly different semantics on OS X
  21. // than on Windows or Linux. FilePathWatcher on Linux and Windows will detect
  22. // modifications to files in a watched directory. FilePathWatcher on Mac will
  23. // detect the creation and deletion of files in a watched directory, but will
  24. // not detect modifications to those files. See file_path_watcher_kqueue.cc for
  25. // details.
  26. //
  27. // Must be destroyed on the sequence that invokes Watch().
  28. class BASE_EXPORT FilePathWatcher {
  29. public:
  30. enum class Type {
  31. // Indicates that the watcher should watch the given path and its
  32. // ancestors for changes. If the path does not exist, its ancestors will
  33. // be watched in anticipation of it appearing later. If the path names a
  34. // directory, changes within the directory are not watched.
  35. kNonRecursive,
  36. // Indicates that the watcher should watch the given path, its ancestors,
  37. // and its descendants for changes. If the path names a directory, changes
  38. // within the directory are watched.
  39. kRecursive,
  40. #if BUILDFLAG(IS_MAC)
  41. // Indicates that the watcher should watch the given path only (neither
  42. // ancestors nor descendants). The watch fails if the path does not exist.
  43. kTrivial,
  44. #endif // BUILDFLAG(IS_MAC)
  45. };
  46. // Callback type for Watch(). |path| points to the file that was updated,
  47. // and |error| is true if the platform specific code detected an error. In
  48. // that case, the callback won't be invoked again.
  49. using Callback =
  50. base::RepeatingCallback<void(const FilePath& path, bool error)>;
  51. // Used internally to encapsulate different members on different platforms.
  52. class PlatformDelegate {
  53. public:
  54. using Type = FilePathWatcher::Type;
  55. PlatformDelegate();
  56. PlatformDelegate(const PlatformDelegate&) = delete;
  57. PlatformDelegate& operator=(const PlatformDelegate&) = delete;
  58. virtual ~PlatformDelegate();
  59. // Start watching for the given |path| and notify |delegate| about changes.
  60. [[nodiscard]] virtual bool Watch(const FilePath& path,
  61. Type type,
  62. const Callback& callback) = 0;
  63. // Stop watching. This is called from FilePathWatcher's dtor in order to
  64. // allow to shut down properly while the object is still alive.
  65. virtual void Cancel() = 0;
  66. protected:
  67. friend class FilePathWatcher;
  68. scoped_refptr<SequencedTaskRunner> task_runner() const {
  69. return task_runner_;
  70. }
  71. void set_task_runner(scoped_refptr<SequencedTaskRunner> runner) {
  72. task_runner_ = std::move(runner);
  73. }
  74. // Must be called before the PlatformDelegate is deleted.
  75. void set_cancelled() {
  76. cancelled_ = true;
  77. }
  78. bool is_cancelled() const {
  79. return cancelled_;
  80. }
  81. private:
  82. scoped_refptr<SequencedTaskRunner> task_runner_;
  83. bool cancelled_ = false;
  84. };
  85. FilePathWatcher();
  86. FilePathWatcher(const FilePathWatcher&) = delete;
  87. FilePathWatcher& operator=(const FilePathWatcher&) = delete;
  88. ~FilePathWatcher();
  89. // Returns true if the platform and OS version support recursive watches.
  90. static bool RecursiveWatchAvailable();
  91. #if BUILDFLAG(IS_LINUX) || BUILDFLAG(IS_CHROMEOS)
  92. // Whether there are outstanding inotify watches.
  93. static bool HasWatchesForTest();
  94. #endif // BUILDFLAG(IS_LINUX) || BUILDFLAG(IS_CHROMEOS)
  95. // Starts watching |path| (and its descendants if |type| is kRecursive) for
  96. // changes. |callback| will be run on the caller's sequence to report such
  97. // changes. Returns true if the watch was started successfully and |callback|
  98. // may one day be run, or false in case of failure (e.g., a recursive watch on
  99. // platforms that do not support such).
  100. //
  101. // On POSIX, this must be called from a thread that supports
  102. // FileDescriptorWatcher.
  103. bool Watch(const FilePath& path, Type type, const Callback& callback);
  104. private:
  105. std::unique_ptr<PlatformDelegate> impl_;
  106. SequenceChecker sequence_checker_;
  107. };
  108. } // namespace base
  109. #endif // BASE_FILES_FILE_PATH_WATCHER_H_