/Users/buildslave/jenkins/workspace/coverage/llvm-project/clang/include/clang/DirectoryWatcher/DirectoryWatcher.h
Line | Count | Source |
1 | | //===- DirectoryWatcher.h - Listens for directory file changes --*- C++ -*-===// |
2 | | // |
3 | | // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. |
4 | | // See https://llvm.org/LICENSE.txt for license information. |
5 | | // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception |
6 | | // |
7 | | //===----------------------------------------------------------------------===// |
8 | | |
9 | | #ifndef LLVM_CLANG_DIRECTORYWATCHER_DIRECTORYWATCHER_H |
10 | | #define LLVM_CLANG_DIRECTORYWATCHER_DIRECTORYWATCHER_H |
11 | | |
12 | | #include "llvm/ADT/ArrayRef.h" |
13 | | #include "llvm/ADT/StringRef.h" |
14 | | #include "llvm/Support/Error.h" |
15 | | #include <functional> |
16 | | #include <memory> |
17 | | #include <string> |
18 | | |
19 | | namespace clang { |
20 | | /// Provides notifications for file changes in a directory. |
21 | | /// |
22 | | /// Invokes client-provided function on every filesystem event in the watched |
23 | | /// directory. Initially the watched directory is scanned and for every file |
24 | | /// found, an event is synthesized as if the file was added. |
25 | | /// |
26 | | /// This is not a general purpose directory monitoring tool - list of |
27 | | /// limitations follows. |
28 | | /// |
29 | | /// Only flat directories with no subdirectories are supported. In case |
30 | | /// subdirectories are present the behavior is unspecified - events *might* be |
31 | | /// passed to Receiver on macOS (due to FSEvents being used) while they |
32 | | /// *probably* won't be passed on Linux (due to inotify being used). |
33 | | /// |
34 | | /// Known potential inconsistencies |
35 | | /// - For files that are deleted befor the initial scan processed them, clients |
36 | | /// might receive Removed notification without any prior Added notification. |
37 | | /// - Multiple notifications might be produced when a file is added to the |
38 | | /// watched directory during the initial scan. We are choosing the lesser evil |
39 | | /// here as the only known alternative strategy would be to invalidate the |
40 | | /// watcher instance and force user to create a new one whenever filesystem |
41 | | /// event occurs during the initial scan but that would introduce continuous |
42 | | /// restarting failure mode (watched directory is not always "owned" by the same |
43 | | /// process that is consuming it). Since existing clients can handle duplicate |
44 | | /// events well, we decided for simplicity. |
45 | | /// |
46 | | /// Notifications are provided only for changes done through local user-space |
47 | | /// filesystem interface. Specifically, it's unspecified if notification would |
48 | | /// be provided in case of a: |
49 | | /// - a file mmap-ed and changed |
50 | | /// - a file changed via remote (NFS) or virtual (/proc) FS access to monitored |
51 | | /// directory |
52 | | /// - another filesystem mounted to the watched directory |
53 | | /// |
54 | | /// No support for LLVM VFS. |
55 | | /// |
56 | | /// It is unspecified whether notifications for files being deleted are sent in |
57 | | /// case the whole watched directory is sent. |
58 | | /// |
59 | | /// Directories containing "too many" files and/or receiving events "too |
60 | | /// frequently" are not supported - if the initial scan can't be finished before |
61 | | /// the watcher instance gets invalidated (see WatcherGotInvalidated) there's no |
62 | | /// good error handling strategy - the only option for client is to destroy the |
63 | | /// watcher, restart watching with new instance and hope it won't repeat. |
64 | | class DirectoryWatcher { |
65 | | public: |
66 | | struct Event { |
67 | | enum class EventKind { |
68 | | Removed, |
69 | | /// Content of a file was modified. |
70 | | Modified, |
71 | | /// The watched directory got deleted. |
72 | | WatchedDirRemoved, |
73 | | /// The DirectoryWatcher that originated this event is no longer valid and |
74 | | /// its behavior is unspecified. |
75 | | /// |
76 | | /// The prime case is kernel signalling to OS-specific implementation of |
77 | | /// DirectoryWatcher some resource limit being hit. |
78 | | /// *Usually* kernel starts dropping or squashing events together after |
79 | | /// that and so would DirectoryWatcher. This means that *some* events |
80 | | /// might still be passed to Receiver but this behavior is unspecified. |
81 | | /// |
82 | | /// Another case is after the watched directory itself is deleted. |
83 | | /// WatcherGotInvalidated will be received at least once during |
84 | | /// DirectoryWatcher instance lifetime - when handling errors this is done |
85 | | /// on best effort basis, when an instance is being destroyed then this is |
86 | | /// guaranteed. |
87 | | /// |
88 | | /// The only proper response to this kind of event is to destruct the |
89 | | /// originating DirectoryWatcher instance and create a new one. |
90 | | WatcherGotInvalidated |
91 | | }; |
92 | | |
93 | | EventKind Kind; |
94 | | /// Filename that this event is related to or an empty string in |
95 | | /// case this event is related to the watched directory itself. |
96 | | std::string Filename; |
97 | | |
98 | | Event(EventKind Kind, llvm::StringRef Filename) |
99 | 52 | : Kind(Kind), Filename(Filename) {} |
100 | | }; |
101 | | |
102 | | /// llvm fatal_error if \param Path doesn't exist or isn't a directory. |
103 | | /// Returns llvm::Expected Error if OS kernel API told us we can't start |
104 | | /// watching. In such case it's unclear whether just retrying has any chance |
105 | | /// to succeed. |
106 | | static llvm::Expected<std::unique_ptr<DirectoryWatcher>> |
107 | | create(llvm::StringRef Path, |
108 | | std::function<void(llvm::ArrayRef<DirectoryWatcher::Event> Events, |
109 | | bool IsInitial)> |
110 | | Receiver, |
111 | | bool WaitForInitialSync); |
112 | | |
113 | 8 | virtual ~DirectoryWatcher() = default; |
114 | | DirectoryWatcher(const DirectoryWatcher &) = delete; |
115 | | DirectoryWatcher &operator=(const DirectoryWatcher &) = delete; |
116 | | DirectoryWatcher(DirectoryWatcher &&) = default; |
117 | | |
118 | | protected: |
119 | 8 | DirectoryWatcher() = default; |
120 | | }; |
121 | | |
122 | | } // namespace clang |
123 | | |
124 | | #endif // LLVM_CLANG_DIRECTORYWATCHER_DIRECTORYWATCHER_H |