clang  14.0.0git
DirectoryWatcher.h
Go to the documentation of this file.
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.
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.
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.
91  };
92 
94  /// Filename that this event is related to or an empty string in
95  /// case this event is related to the watched directory itself.
97 
98  Event(EventKind Kind, llvm::StringRef Filename)
99  : 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.
107  create(llvm::StringRef Path,
108  std::function<void(llvm::ArrayRef<DirectoryWatcher::Event> Events,
109  bool IsInitial)>
110  Receiver,
111  bool WaitForInitialSync);
112 
113  virtual ~DirectoryWatcher() = default;
114  DirectoryWatcher(const DirectoryWatcher &) = delete;
115  DirectoryWatcher &operator=(const DirectoryWatcher &) = delete;
116  DirectoryWatcher(DirectoryWatcher &&) = default;
117 
118 protected:
119  DirectoryWatcher() = default;
120 };
121 
122 } // namespace clang
123 
124 #endif // LLVM_CLANG_DIRECTORYWATCHER_DIRECTORYWATCHER_H
clang::DirectoryWatcher::~DirectoryWatcher
virtual ~DirectoryWatcher()=default
string
string(SUBSTRING ${CMAKE_CURRENT_BINARY_DIR} 0 ${PATH_LIB_START} PATH_HEAD) string(SUBSTRING $
Definition: CMakeLists.txt:22
clang::DirectoryWatcher::Event::EventKind::WatchedDirRemoved
@ WatchedDirRemoved
The watched directory got deleted.
clang::DirectoryWatcher::Event::Kind
EventKind Kind
Definition: DirectoryWatcher.h:93
llvm::Expected
Definition: LLVM.h:41
clang::DirectoryWatcher::Event::EventKind
EventKind
Definition: DirectoryWatcher.h:67
clang::DirectoryWatcher::Event::EventKind::Modified
@ Modified
Content of a file was modified.
clang::DirectoryWatcher::operator=
DirectoryWatcher & operator=(const DirectoryWatcher &)=delete
clang::DirectoryWatcher::DirectoryWatcher
DirectoryWatcher()=default
clang::DirectoryWatcher::Event::Filename
std::string Filename
Filename that this event is related to or an empty string in case this event is related to the watche...
Definition: DirectoryWatcher.h:96
clang::DirectoryWatcher::Event
Definition: DirectoryWatcher.h:66
clang::DirectoryWatcher
Provides notifications for file changes in a directory.
Definition: DirectoryWatcher.h:64
clang::DirectoryWatcher::Event::Event
Event(EventKind Kind, llvm::StringRef Filename)
Definition: DirectoryWatcher.h:98
clang::DirectoryWatcher::Event::EventKind::WatcherGotInvalidated
@ WatcherGotInvalidated
The DirectoryWatcher that originated this event is no longer valid and its behavior is unspecified.
clang::DirectoryWatcher::create
static llvm::Expected< std::unique_ptr< DirectoryWatcher > > create(llvm::StringRef Path, std::function< void(llvm::ArrayRef< DirectoryWatcher::Event > Events, bool IsInitial)> Receiver, bool WaitForInitialSync)
llvm fatal_error if
Definition: DirectoryWatcher-not-implemented.cpp:14
llvm::ArrayRef
Definition: LLVM.h:34
clang
Definition: CalledOnceCheck.h:17
clang::DirectoryWatcher::Event::EventKind::Removed
@ Removed