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 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 : 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 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 125