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