blob: 4f132aff78a9ff1ecaaac08ec945d0adc8028a49 [file] [log] [blame]
James Robinson646469d2014-10-03 15:33:28 -07001// 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
5// This module provides a way to monitor a file or directory for changes.
6
7#ifndef BASE_FILES_FILE_PATH_WATCHER_H_
8#define BASE_FILES_FILE_PATH_WATCHER_H_
9
10#include "base/base_export.h"
11#include "base/basictypes.h"
12#include "base/callback.h"
13#include "base/files/file_path.h"
14#include "base/memory/ref_counted.h"
James Robinsonf19b1022015-05-05 18:12:15 -070015#include "base/single_thread_task_runner.h"
James Robinson646469d2014-10-03 15:33:28 -070016
17namespace base {
18
19// This class lets you register interest in changes on a FilePath.
20// The callback will get called whenever the file or directory referenced by the
21// FilePath is changed, including created or deleted. Due to limitations in the
22// underlying OS APIs, FilePathWatcher has slightly different semantics on OS X
23// than on Windows or Linux. FilePathWatcher on Linux and Windows will detect
24// modifications to files in a watched directory. FilePathWatcher on Mac will
25// detect the creation and deletion of files in a watched directory, but will
26// not detect modifications to those files. See file_path_watcher_kqueue.cc for
27// details.
28class BASE_EXPORT FilePathWatcher {
29 public:
30 // Callback type for Watch(). |path| points to the file that was updated,
31 // and |error| is true if the platform specific code detected an error. In
32 // that case, the callback won't be invoked again.
33 typedef base::Callback<void(const FilePath& path, bool error)> Callback;
34
35 // Used internally to encapsulate different members on different platforms.
36 class PlatformDelegate : public base::RefCountedThreadSafe<PlatformDelegate> {
37 public:
38 PlatformDelegate();
39
40 // Start watching for the given |path| and notify |delegate| about changes.
41 virtual bool Watch(const FilePath& path,
42 bool recursive,
43 const Callback& callback) WARN_UNUSED_RESULT = 0;
44
45 // Stop watching. This is called from FilePathWatcher's dtor in order to
46 // allow to shut down properly while the object is still alive.
47 // It can be called from any thread.
48 virtual void Cancel() = 0;
49
50 protected:
51 friend class base::RefCountedThreadSafe<PlatformDelegate>;
52 friend class FilePathWatcher;
53
54 virtual ~PlatformDelegate();
55
56 // Stop watching. This is only called on the thread of the appropriate
57 // message loop. Since it can also be called more than once, it should
58 // check |is_cancelled()| to avoid duplicate work.
59 virtual void CancelOnMessageLoopThread() = 0;
60
James Robinsonf19b1022015-05-05 18:12:15 -070061 scoped_refptr<base::SingleThreadTaskRunner> task_runner() const {
62 return task_runner_;
James Robinson646469d2014-10-03 15:33:28 -070063 }
64
James Robinsonf19b1022015-05-05 18:12:15 -070065 void set_task_runner(
66 scoped_refptr<base::SingleThreadTaskRunner> task_runner) {
67 task_runner_ = task_runner.Pass();
James Robinson646469d2014-10-03 15:33:28 -070068 }
69
70 // Must be called before the PlatformDelegate is deleted.
71 void set_cancelled() {
72 cancelled_ = true;
73 }
74
75 bool is_cancelled() const {
76 return cancelled_;
77 }
78
79 private:
James Robinsonf19b1022015-05-05 18:12:15 -070080 scoped_refptr<base::SingleThreadTaskRunner> task_runner_;
James Robinson646469d2014-10-03 15:33:28 -070081 bool cancelled_;
82 };
83
84 FilePathWatcher();
85 virtual ~FilePathWatcher();
86
87 // A callback that always cleans up the PlatformDelegate, either when executed
88 // or when deleted without having been executed at all, as can happen during
89 // shutdown.
90 static void CancelWatch(const scoped_refptr<PlatformDelegate>& delegate);
91
92 // Returns true if the platform and OS version support recursive watches.
93 static bool RecursiveWatchAvailable();
94
95 // Invokes |callback| whenever updates to |path| are detected. This should be
96 // called at most once, and from a MessageLoop of TYPE_IO. Set |recursive| to
97 // true, to watch |path| and its children. The callback will be invoked on
98 // the same loop. Returns true on success.
99 //
100 // Recursive watch is not supported on all platforms and file systems.
101 // Watch() will return false in the case of failure.
102 bool Watch(const FilePath& path, bool recursive, const Callback& callback);
103
104 private:
105 scoped_refptr<PlatformDelegate> impl_;
106
107 DISALLOW_COPY_AND_ASSIGN(FilePathWatcher);
108};
109
110} // namespace base
111
112#endif // BASE_FILES_FILE_PATH_WATCHER_H_